Package ca.cgjennings.apps.arkham.component.design

Class ConsequenceSet

  • All Implemented Interfaces:
    java.lang.Iterable<java.lang.String>
    public class ConsequenceSet
extends java.lang.Object
implements java.lang.Iterable<java.lang.String>
    A consequence set formatter formats an ordered list of possible verbal design consequences. In this context, a design consequence refers to the possibly unintended and often hard-to-predict side effects of a design decision that result from trying to balance competing concerns in an ill-structured problem space. The consequence set formatter helps the user to visualize how these consequences change over time as design proceeds by comparing the consequences of the previous design iteration to the current design.

    During a design support analysis, the design analyzer goes through each of the possible consequences, in order, and indicates whether it applies to the current design. The consequence set formatter will compare how the consequences have changed between the current design and the previous design, and use different formatting to provide visual feedback of which consequences are the same, which no longer apply, and which are new.

    Consequences may be divided into categories, with a separate formatter for each category. Because all formatting is written to a StringBuilder provided by the caller, the results from each category can easily be collected into a single formatted document.

    If for some reason you cannot process each possible consequence in the same order for each analysis, this class will not produce reliable results. However, you could build your own formatter using the Diff algorithm.

    Typically, the output produced by this class is a formatted HTML list, but it can be customized to produce other formats, including plain text.

    Since:
    0.9
    Author:
    Chris Jennings

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static int DELETED
      Comparison code for a consequence that was present in the previous set but isn't now.
      protected static int INSERTED
      Comparison code for a consequence that is present in the current set but not the previous one.
      protected static int KEPT
      Comparison code for a consequence that is present in both sets.

    • Constructor Summary

      Constructors 
      Constructor Description
      ConsequenceSet()
      Create a consequence set with an empty category name.
      ConsequenceSet​(java.lang.String category)
      Create a consequence set with a specific category name.
      ConsequenceSet​(java.lang.String category, java.awt.Color color)
      Create a consequence set with a specific category name and installs a default style for the given colour.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(java.lang.String consequence)
      Adds the next consequence to the set.
      void formatConsequences​(java.lang.StringBuilder b, ConsequenceSet predecessor, java.lang.String preamble)
      Creates a formatted list of consequences that compares the current design state to the previous design state and appends them to the string builder.
      java.lang.String getCategory()
      Returns the category name for this formatter.
      void installDefaultStyle​(java.awt.Color color)
      Sets all of the markup for the list to a set of suitable defaults for writing HTML documents.
      java.util.Iterator<java.lang.String> iterator()
      Returns an iterator over the consequences in the set.
      void reset()
      Clears the current consequence list.
      void setCategory​(java.lang.String category)
      Sets the category name for this formatter.
      void setDeletedEntryMarkup​(java.lang.String prologue, java.lang.String epilogue)
      Sets the markup to write before and after the text of a deleted entry.
      void setEntrySeparatorMarkup​(java.lang.String separator)  
      void setKeptEntryMarkup​(java.lang.String prologue, java.lang.String epilogue)
      Sets the markup to write before and after the text of an entry that does not change from the previous consequence set to this one.
      void setListMarkup​(java.lang.String prologue, java.lang.String epilogue)
      Sets the markup written to start and the list.
      void setNewEntryMarkup​(java.lang.String prologue, java.lang.String epilogue)
      Sets the markup to write before and after the text of a new entry that was not present in the previous consequence set.
      int size()
      Returns the number of consequences that have been added to the set.
      protected void writeCategory​(java.lang.StringBuilder b)
      Writes markup before the start of the list to describe the category.
      protected void writeEntry​(java.lang.StringBuilder b, java.lang.String entry, int comparison, int undeletedItemNumber)
      Writes a decorated consequence list entry into the string builder.
      protected void writeListHead​(java.lang.StringBuilder b, java.lang.String listHead)
      Writes markup to start the consequence list.
      protected void writeListSeparator​(java.lang.StringBuilder b, java.lang.String listSeparator)
      Writes markup to separate one list entry from another.
      protected void writeListTail​(java.lang.StringBuilder b, java.lang.String listTail)
      Writes markup to end the formatting of a list.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Field Detail

      • DELETED

        protected static final int DELETED
        Comparison code for a consequence that was present in the previous set but isn't now.
        See Also:
        Constant Field Values

      • KEPT

        protected static final int KEPT
        Comparison code for a consequence that is present in both sets.
        See Also:
        Constant Field Values

      • INSERTED

        protected static final int INSERTED
        Comparison code for a consequence that is present in the current set but not the previous one.
        See Also:
        Constant Field Values

    • Constructor Detail

      • ConsequenceSet

        public ConsequenceSet()
        Create a consequence set with an empty category name.

      • ConsequenceSet

        public ConsequenceSet​(java.lang.String category)
        Create a consequence set with a specific category name.
        Parameters:
        category - the category title

      • ConsequenceSet

        public ConsequenceSet​(java.lang.String category,
                      java.awt.Color color)
        Create a consequence set with a specific category name and installs a default style for the given colour.
        Parameters:
        category - the category title
        color - the colour to use for the default style

    • Method Detail

      • add

        public void add​(java.lang.String consequence)
        Adds the next consequence to the set. If a string equal to this consequence is already in the set, the set will not be modified.
        Parameters:
        consequence - the consequence to add
        Throws:
        java.lang.NullPointerException - if the consequence text is null

      • reset

        public void reset()
        Clears the current consequence list. This can be called to reuse an existing consequence set.

      • size

        public int size()
        Returns the number of consequences that have been added to the set.
        Returns:
        the number of consequences in the set

      • iterator

        public java.util.Iterator<java.lang.String> iterator()
        Returns an iterator over the consequences in the set.
        Specified by:
        iterator in interface java.lang.Iterable<java.lang.String>
        Returns:
        an iterator that can be used to examine the items in the set

      • getCategory

        public java.lang.String getCategory()
        Returns the category name for this formatter. This describes the general category of consequences included in the set, if more than one category is being used.
        Returns:
        the category name for the formatter, or null

      • setCategory

        public void setCategory​(java.lang.String category)
        Sets the category name for this formatter. The category name, if any, is typically printed at the top of the consequence list. It may be null to indicate that categories are not being used.
        Parameters:
        category - the name of the category that the consequence set is associated with

      • installDefaultStyle

        public void installDefaultStyle​(java.awt.Color color)
        Sets all of the markup for the list to a set of suitable defaults for writing HTML documents. The list text will use the specified colour, or black if color is null.
        Parameters:
        color - the colour to use for the list entries

      • setDeletedEntryMarkup

        public void setDeletedEntryMarkup​(java.lang.String prologue,
                                  java.lang.String epilogue)
        Sets the markup to write before and after the text of a deleted entry. Typically this will include a &lt;li&gt; tag pair and some style instructions.
        Parameters:
        prologue - the markup to write before the entry, or null to suppress the entry
        epilogue - the markup to write after the entry

      • setKeptEntryMarkup

        public void setKeptEntryMarkup​(java.lang.String prologue,
                               java.lang.String epilogue)
        Sets the markup to write before and after the text of an entry that does not change from the previous consequence set to this one. Typically this will include a &lt;li&gt; tag pair and some style instructions.
        Parameters:
        prologue - the markup to write before the entry, or null to suppress the entry
        epilogue - the markup to write after the entry

      • setNewEntryMarkup

        public void setNewEntryMarkup​(java.lang.String prologue,
                              java.lang.String epilogue)
        Sets the markup to write before and after the text of a new entry that was not present in the previous consequence set. Typically this will include a &lt;li&gt; tag pair and some style instructions.
        Parameters:
        prologue - the markup to write before the entry, or null to suppress the entry
        epilogue - the markup to write after the entry

      • setListMarkup

        public void setListMarkup​(java.lang.String prologue,
                          java.lang.String epilogue)
        Sets the markup written to start and the list.
        Parameters:
        prologue - the markup to start a list, e.g., &lt;ol&gt;
        epilogue - the markup to end a list, e.g., &lt;/ol&gt;

      • setEntrySeparatorMarkup

        public void setEntrySeparatorMarkup​(java.lang.String separator)

      • formatConsequences

        public void formatConsequences​(java.lang.StringBuilder b,
                               ConsequenceSet predecessor,
                               java.lang.String preamble)
        Creates a formatted list of consequences that compares the current design state to the previous design state and appends them to the string builder.
        Parameters:
        b - the buffer to append to
        predecessor - the consequence set for the previous design state, or null
        preamble - an optional preamble to write after the category and before the start of the list (if any), or null

      • writeCategory

        protected void writeCategory​(java.lang.StringBuilder b)
        Writes markup before the start of the list to describe the category. Typically does nothing if the category is null or an empty stirng.
        Parameters:
        b - the destination for the markup text

      • writeListHead

        protected void writeListHead​(java.lang.StringBuilder b,
                             java.lang.String listHead)
        Writes markup to start the consequence list.
        Parameters:
        b - the destination for the markup text
        listHead - the current list heading markup

      • writeEntry

        protected void writeEntry​(java.lang.StringBuilder b,
                          java.lang.String entry,
                          int comparison,
                          int undeletedItemNumber)
        Writes a decorated consequence list entry into the string builder. The base class will use the currently set markup for the entry type to compose the entry, replacing the text @n; with the undeleted item number.
        Parameters:
        b - the destination for the markup text
        entry - the string that describes the consequence
        comparison - the entry style to use; one of DELETED, KEPT or INSERTED
        undeletedItemNumber - this is the suggested number to use if writing a numbered list; it is incremented for each entry unless the entry is being deleted from the list

      • writeListSeparator

        protected void writeListSeparator​(java.lang.StringBuilder b,
                                  java.lang.String listSeparator)
        Writes markup to separate one list entry from another.
        Parameters:
        b - the destination for the markup text
        listSeparator - the current list separator markup

      • writeListTail

        protected void writeListTail​(java.lang.StringBuilder b,
                             java.lang.String listTail)
        Writes markup to end the formatting of a list.
        Parameters:
        b - the destination for the markup text
        listTail - the current list tail markup