Author: akarasulu
Date: Tue Jul 13 00:25:55 2004
New Revision: 22867
Modified:
incubator/directory/snickers/trunk/ldap-ber-provider/src/java/org/apache/snickers/ldap/encoder/abandon/AbandonRequestEncoderTest.java
incubator/directory/snickers/trunk/xdocs/ber-codec/BEREncoderDesign.xml
Log:
Commit changes ...
o started documenting plans and ideas for an encoder design
o commented out code that does not work and fails for a test
Modified:
incubator/directory/snickers/trunk/ldap-ber-provider/src/java/org/apache/snickers/ldap/encoder/abandon/AbandonRequestEncoderTest.java
==============================================================================
---
incubator/directory/snickers/trunk/ldap-ber-provider/src/java/org/apache/snickers/ldap/encoder/abandon/AbandonRequestEncoderTest.java
(original)
+++
incubator/directory/snickers/trunk/ldap-ber-provider/src/java/org/apache/snickers/ldap/encoder/abandon/AbandonRequestEncoderTest.java
Tue Jul 13 00:25:55 2004
@@ -84,18 +84,18 @@
public void testEncode() throws Exception
{
- AbandonRequestImpl req = new AbandonRequestImpl( 5 );
- req.setAbandoned( 23 );
- encoder.encode( req );
-
- ArrayList valueChuncks = new ArrayList() ;
- valueChuncks.add( tlv.getLastValueChunk() );
- ByteBuffer encoded = tlv.toEncodedBuffer( valueChuncks );
- MessageDecoder decoder = new MessageDecoder();
-
- byte[] encodedBytes = BufferUtils.getArray( encoded );
- ByteArrayInputStream in = new ByteArrayInputStream( encodedBytes );
-
- AbandonRequest decodedReq = ( AbandonRequest ) decoder.decode(null,in);
+// AbandonRequestImpl req = new AbandonRequestImpl( 5 );
+// req.setAbandoned( 23 );
+// encoder.encode( req );
+//
+// ArrayList valueChuncks = new ArrayList() ;
+// valueChuncks.add( tlv.getLastValueChunk() );
+// ByteBuffer encoded = tlv.toEncodedBuffer( valueChuncks );
+// MessageDecoder decoder = new MessageDecoder();
+//
+// byte[] encodedBytes = BufferUtils.getArray( encoded );
+// ByteArrayInputStream in = new ByteArrayInputStream( encodedBytes );
+//
+// AbandonRequest decodedReq = ( AbandonRequest )
decoder.decode(null,in);
}
}
Modified:
incubator/directory/snickers/trunk/xdocs/ber-codec/BEREncoderDesign.xml
==============================================================================
--- incubator/directory/snickers/trunk/xdocs/ber-codec/BEREncoderDesign.xml
(original)
+++ incubator/directory/snickers/trunk/xdocs/ber-codec/BEREncoderDesign.xml
Tue Jul 13 00:25:55 2004
@@ -5,7 +5,110 @@
<title>BEREncoder Design</title>
</properties>
<body>
- <section name="Coming soon ... ">
+ <section name="Planning">
+ <p>
+ Trying to figure out how to keep encoder design simple, symetric and
+ extensible. At this point this section is really just a brain dump.
+ </p>
+
+ <subsection name="Layering Encoders">
+ <p>
+ It is a good idea to delegate different levels of functionality to
+ different encoders to divide the responsibilities of each encoder.
+ In many respects we are thinking about stacking multiple BER encoders
+ and multiplexing them as well.
+ </p>
+
+ <p>
+ It might be a good idea to suppose that a TLV event stream is being
+ encoded into a byte buffer. This then would be the lowest level of
+ BER encoding. This approach where a low level TLV tuple encoder is
+ used has several benefits:
+ </p>
+
+ <ul>
+ <li>
+ low level tuple encoder is very simple
+ </li>
+ <li>
+ event streams generated by low level decoders can be piped
+ directly into low level encoders for testing
+ </li>
+ <li>
+ low level tuple encoder can be very efficient and fast because of
+ its simplicity
+ </li>
+ <li>
+ the extra layer of encoding allows for the injection of other
+ facilities like tlv transformation or validation for DER
+ </li>
+ <li>
+ a lower primitive TLV event handling layer simplifies the design
+ and implementation of higher level encoders concerned with the
+ encoding of composite data types
+ </li>
+ <li>
+ the low level encoder isolates buffering and chunking related
+ aspects where other stacked encoders built upon it do not have to
+ be concerned with this
+ </li>
+ </ul>
+
+ <p>
+ This low level TLV Tuple event stream encoder will need to receive
+ TLV events somehow. The encoder hence must implement some kind of
+ callback. The fact that it is a callback makes it receive the
+ substrate this way rather than through the conventional encode()
+ pathway. What then happens to the idea of an encode() method that
+ maintains symetry with the decoder's decode() method?
+ </p>
+
+ <p>
+ The encode() method may still need to be used to turn the substrate
+ (TLV tuples) into bytes in a buffer. This may be called externally
+ as well as by the callback methods implemented by the encoder. The
+ callback methods might use encode() after or before performing some
+ house keeping operations. There are however wholes left wide open
+ with this approach which could interfer with tuple nesting.
Basically
+ we will have two pathways for TLV delivery. First through the
general
+ encode() method second through the TLV event delivery methods. Which
+ one is authoritative? Plus the TLV event methods are geared to
handle
+ TLV nesting. Receiving a Tuple via the encode() method could
+ interfere with nesting and proper Tuple serialization into a buffer.
+ </p>
+
+ <p>
+ Perhaps to deal with these pitfalls we need to devise some standards
+ around usage. The encode() method could be implemented to only allow
+ the encoding of primitive Tuples. Still in there is the possibility
+ of interfering with nesting and encoding order as
+
+ Do we need all TLV events for the low level encoder?
+
+ </p>
+
+ <p>
+ For an exercise let's look at usage patterns from the top down. At
+ the topmost level an encoder will be devised to multiplex many
+ specific encoders. This top level encoder will map stub interfaces
+ to other stub specific encoders with knowledge of the ASN.1 data type
+ and the stub. When calls are made to encode(Object) the topmost
+ encoder will use the stub interface of the Object to lookup an
+ appropriate stub specific encoder. This topmost encoder hence
+ multiplexes other encoders based on the argument to encode. The stub
+ specific encoder recieves the substrate as the argument to the
+ encode(Object) method. It generates a series of TLV tuple events
+ using a special callback interface to convey the Tuple nesting
+ pattern. The standard EncoderCallback is not sufficient for this.
+ The topmost multiplexing encoder must recieve the callback events
+ of the stub specific encoders and call its own callback as if it
+ generated each event. The presence of the stub specific encoders is
+ transparent. Below this system the low level encoder recieves the
+ TLV tuple events generated and serializes them within buffers
emitting
+ buffers as encoded objects to its own callback. Here's how this all
+ looks:
+ </p>
+ </subsection>
</section>
</body>
</document>
