This post originated from an RSS feed registered with Java Buzz by Wilfred Springer. Original Post: Preon changes Feed Title: Distributed Reflections of the Third Kind Feed URL: http://blog.flotsam.nl/feeds/posts/default/-/Java Feed Description: Anything coming to my mind having to do with Java Latest Java Buzz Posts Latest Java Buzz Posts by Wilfred Springer Latest Posts From Distributed Reflections of the Third Kind

package nl.flotsam.preon;

import nl.flotsam.pecia.Contents;
import nl.flotsam.pecia.Documenter;
import nl.flotsam.pecia.ParaContents;

public interface CodecDescriptor {

   /**
    * An enumeration with different adjectives.
    */
   public enum Adjective {
       A, THE, NONE;
      
       public String asTextPreferA() {
           switch(this) {
               case A: return "a ";
               case THE: return "the ";
               default: return "";
           }
       }

       public String asTextPreferAn() {
           switch(this) {
               case A: return "an ";
               case THE: return "the ";
               default: return "";
           }
       }
      
   }

   /**
    * Returns an object capable of writing a one-line summary of the data
    * structure. Expect the summary to be printed at the beginning of a
    * paragraph, but make sure the paragraph is ended in such a way that more
    * lines might be appended to that paragraph, if required, by some other
    * component. I.e. make sure you end with a dot-space. (". ") Typically
    * starts with {@link Adjective#A}. 
    *
    */
   <C extends ParaContents<?>> Documenter<C> summary();

   /**
    * Returns an object capable of rendering a short reference to the type of
    * data for which the Codec provides the decoder. This reference should
    * <em>at least</em> include a reference to the type of data decoded by
    * 'sub'-Codecs. The {@link Adjective} argument allows the implementor to
    * generate a correct reference, such as 'a list' instead of 'an list'.
    *
    * <p>
    * Note that implementers should assume that the particular piece of data
    * that is going to be referenced here will be detailed further along the
    * road. Unless {@link #requiresDedicatedSection()} returns
    * <code>true</code>, that could be within the same section.
    * </p>
    *
    * @param adjective
    *            The adjective to use; <code>null</code> if no adjective should
    *            be used.
    */
   <C extends ParaContents<?>> Documenter<C> reference(Adjective adjective);

   /**
    * Returns an object capable of writing detailed information on the format
    * to the document section passed in. Typically implemented by writing a
    * (couple of) paragraph(s), and forwarding to the CodecDescriptor of a
    * nested {@linkplain Codec}. Note that - while forwarding - the descriptor
    * has the option to replace the way the buffer is referenced.
    *
    * @param bufferReference
    *            A String based human readable reference to the encoded data.
    */
   <C extends Contents<?>> Documenter<C> details(String bufferReference);

   /**
    * Returns a boolean indicating if the type of data for which the Codec
    * provides the decoder should be documented in a dedicated section.
    *
    * @return A boolean indicating if the type of data for which the Codec
    *         provides the decoder should be documented in a dedicated section:
    *         <code>true</code> if it does; <code>false</code> if it doesn't.
    */
   boolean requiresDedicatedSection();

   /**
    * Returns the title of the section to be rendered, in case
    * {@link #requiresDedicatedSection()} returns <code>true</code>.
    *
    * @return The title of the section to be rendered, in case
    *         {@link #requiresDedicatedSection()} returns <code>true</code>.
    */
   String getTitle();

}