Class ConsequenceSet
- java.lang.Object
-
- ca.cgjennings.apps.arkham.component.design.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.
-
-
-
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 titlecolor
- 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 isnull
-
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 interfacejava.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 benull
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 isnull
.- 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<li>
tag pair and some style instructions.- Parameters:
prologue
- the markup to write before the entry, ornull
to suppress the entryepilogue
- 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<li>
tag pair and some style instructions.- Parameters:
prologue
- the markup to write before the entry, ornull
to suppress the entryepilogue
- 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<li>
tag pair and some style instructions.- Parameters:
prologue
- the markup to write before the entry, ornull
to suppress the entryepilogue
- 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.,<ol>
epilogue
- the markup to end a list, e.g.,</ol>
-
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 topredecessor
- the consequence set for the previous design state, ornull
preamble
- an optional preamble to write after the category and before the start of the list (if any), ornull
-
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 isnull
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 textlistHead
- 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 textentry
- the string that describes the consequencecomparison
- the entry style to use; one ofDELETED
,KEPT
orINSERTED
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 textlistSeparator
- 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 textlistTail
- the current list tail markup
-
-