SimulatorAlive Files

2.7.0 Alpha (9/6/2020)
	Added a new method to Hierarchy: encode(HierarchyEncoder,Hierarchy) is used
		for passing options to the methods that pass data on to the
		HierarchyEncoder
	Gave Hierarchy the ability to encode comments for the original source of
		nodes and attributes; This uses three boolean attributes in the options
		Hierarchy passed along-side the HierarchyEncoder:
		"Source Comment Attributes" turns on source comments for attributes,
		"Source Comment Nodes" turns it on for nodes and "Source Comment" turns
		it on for both

2.6.1 Alpha (8/30/2020)
	Fixed a bug in Hierarchy.copyTo(Hierarchy) that was introduced in 2.5.0
		Alpha

2.6.0 Alpha (8/29/2020)
	Found and fixed a bug in the new getAttributeSource(String) method that was
		causing a NullPointerException to be thrown
	Added a pair of new methods to Hierarchy: getSource() and setSource() allow
		getting and setting source data for the node itself; Internally, this
		works via setAttributeSource and getAttributeSource, so there was no
		need to update any sub-Class of Hierarchy; The node source data is keyed
		to the null String
	Modified the XML parser to set source data for nodes and the base Hierarchy
	Added a new constructor to HierarchyXMLDecoder to allow setting the system
		ID for the document
	Found some parts of the XML parser that weren't setting source data (legacy
		attributes) and fixed them to do so
	Modified SimpleHierarchy to remove source data for an attribute just before
		that attribute is removed

2.5.0 Alpha (8/28/2020)
	Added a pair of new methods to Hierarchy for handling location data attached
		to an attribute and modified all Hierarchy sub-Classes appropriately to
		use this; These methods are setAttributeSource(String,String and
		getAttributeSource(String)
	Discovered that the Hierarchy.copyTo method was copying all attributes as
		Strings and fixed it
	Added a new method to Hierarchy: parseFromXML(InputStream,String) allows
		associating a location with data from the InputStream, which can be very
		helpful in finding errors in bad XML files
	Modified the method parseXMLZip in Hierarchy to use the above new method,
		providing the parser with data on each XML file in the zip, in the form
		of a jar file uri
	Modified the XML parser for Hierarchy to call the
		setAttributeSource(String,String) method after each attribute is set,
		unless there is no valid location data; This will allow data to be read
		from disk and then used at different times, while still allowing
		well-formed, but incorrect, Hierarchy data to be debugged

2.4.0 Alpha (8/11/2020)
	Added a new interface to the net.sf.simulatoralive.hierarchy package:
		HierarchyEncoder describes the methods required for encoding hierarchy
		data
	Added a new interface to the net.sf.simulatoralive.hierarchy package:
		HierarchyDecoder describes the methods required for decoding hierarchy
		data
	Modified the raw unparser to throw a java.lang.RuntimeException on a failed
		encode, instead of silently ignoring it; This is an impossible
		condition, but bears handling with a proper Exception, in case I'm wrong
		about that
	Added a new Class to the net.sf.simulatoralive.hierarchy package:
		HierarchyXMLEncoder implements HierarchyEncoder and it's methods produce
		XML output via a wrapped PrintStream
	Re-worked Hierarchy.storeToXML(OutputStream,Hierarchy) to use the above to
		do it's work
	Found and fixed a bug that was causing character array data to be output to
		XML without enclosing quotes; This bug was causing an XML file output by
		this library to throw an IllegalArgumentException on an attempt to read
		the file in
	Made some small changes to XML output formats to make them more consistent:
		raw attributes are no longer saved if they can't have a type associated
		with them, same goes for String arrays
	Modified the SAX parser for Hierarchy to handle exceptions better; Those old
		IllegalArgumentExceptions are now being wrapped in SAXParserExceptions
		early on and they're now getting proper location data tagged to them;
		This should significantly help with finding and fixing syntax errors in
		XML files
	Added a new Class to the net.sf.simulatoralive.hierarchy package:
		HierarchyXMLDecoder implements HierarchyDecoder and allows decoding XML
		hierarchy data from a stream or file
	Added a new Class to the net.sf.simulatoralive.hierarchy package:
		HierarchyBinaryEncoder implements HierarchyEncoder and allows encoding
		hierarchy data in a new binary format that's described in the file
		'doc/hierarchy-binary-encoding.txt'
	Added a new Class to the net.sf.simulatoralive.hierarchy package:
		HierarchyBinaryDecoder implements HierarchyDecoder and allows decoding
		hierarchy data as written by HierarchyBinaryEncoder

2.3.5 Alpha (6/13/2017)
	Changed the type of Exception thrown by customized parsing from a mixture of
		SAXException and HierarchyException to SAXParseException; this allowed
		associating a location within the document with the Exceptions being
		thrown

2.3.4 Alpha (7/18/2016)
	Fixed a nasty case of infinite recursion involving boolean arrays casting to
		boolean arrays; boy did I screw up on that one...

2.3.3 Alpha (5/24/2016)
	Moved HierarchyContentHandler out of the parseFromXML(InputStream) method
		and made it work in the new context
	Addded a new method: parseFromXML(File); it's purpose should be obvious
	Deprecated the parseXMLFile method in favor of the above method and
		re-worked it internally to use it

2.3.2 Alpha (2/21/2016)
	Added a two new XML tags intended just for input, which are demonstrated in
		doc/XML-v2.xml; These are <delete-node> and <delete-attribute>
	To delete an existing node use like this ("/" in the name is allowed, to
		specify a node on another level):
		<delete-node name="Name of Node"/>
	To delete a single attribute, use like this ("/" is allowed here, too): 
		<delete-attribute name="Name of Attribute"/>
	To delete all of a node's attributes, omit the name
	The above changes were made to complement the changes from the previous
		release, allowing a separate file to erase specific data added by a
		previously read XML file

2.3.1 Alpha (2/18/16)
	Added static methods to Hierarchy for reading XML files into a Hierarchy;
		parseXMLFile() reads a single file; parseXMLDirectory() reads multiple
		XML files from a directory (optionally recursively) and merges them all
		into the Hierarchy; parseXMLZip does the same, but scans an entire Zip
		file archive for XML files to read
	Added to the existing API documentation to get JavaDoc to shut up about the
		dozen or so pointless warnings I got sick of seeing, since they were
		getting in the way of finding the actual errors

2.3.0 Alpha (2/16/16)
	The AttributeCaster.toX(String) methods were throwing NumberFormatException;
		it's now ClassCastException to fit with the rest of the class, since
		they're considered type-casting methods, not parsers
	Fixed an XML indentation bug I accidentally introduced in the previous
		version
	Added some methods to AttributeCaster to produce hexidecimal Strings
	Dropped support for the trailing "h" hexidecimal identifier; it's simpler
		for everything to have just one identifier
	Added a method to AttributeCaster that turns a boolean array into a string
		composed of ones and zeros
	Added the ability to parse a boolean array from a String of ones and zeros;
		this is automatically detected and used; no special identifier is
		required
	Fixed an error related to char[] String data being left in encoded form when
		parsed from an XML file
	Added more export options
	Added some constants to HierarchyHelper that provide pre-configured
		Hierarchy instances for getting
		Hierarchy.storeToXML(OutputStream,Hierarchy) to produce XML resembling
		each version of this library's default output format
	Made the parseFromXML(InputStream) method throw a SAXException when a '/'
		character is found in a node name
	Made some (annoying) source alterations to get Java 8's JavaDoc command to
		shut the frick up; it was all good JavaDoc comments under 1.4.2, so
		what's the deal in producing actual errors on what worked before?
	Added a CSS stylesheet 'src/stylesheet.css' file to force the API to
		resemble pre-Java 7 API docs, since I couldn't stand to look at that
		utterly awful theme (with less documentation clarity) that Oracle chose
		to use; It's an MIT licensed file I found that is alomst a perfect copy
		of the old-style theme
	Added the ability to tack a name onto a hierarchy tag in the XML input like
		so: <hierarchy name="1/2/3">, allowing you to specify a tree of empty
		nodes above the bottom level; This should make it easier to define such
		unbranching trees more easily, rather than laying out the nodes in
		overly verbose text
	Added some additional error checking to Hierarchy.parseFromXML(InputStream);
		It's now throwing some additional SAXExceptions when odd-ball, crazy
		crap is done

2.2.0 Alpha (9/21/12) [Unreleased]
	Added methods for handling String arrays as a regular type; their ugly
		format in an XML file is the main reason for the next change
	Added many new elements for parsing XML files with Hierarchy: one for each
		data type that Hierarchy can parse; their names are the same as the old
		types, except that "[]" in array types has been replaced with the suffix
		"-array" due to XML formatting issues; the values for these are
		parsed from the character body of the elements; The new way is less
		verbose (always good!) and allows String arrays to be left in a more
		readable form in XML files; users used to the old format will be happy
		to hear that the old form will still work; the following is an example,
		followed by it's older equivalent:
		<int name="Integer">25</int>
		<attribute name="Integer" type="int" value="25"/>
	Modified Hierarchy to write the new XML elements described above; the old
		"attribute" tags are no longer written to the OutputSreeam by default
	Added a new method: Hierarchy.storeToXML(OutputStream,Hierarchy); this
		allows you to adjust the format used for XML output by passing a
		reference to a Hierarchy along with the OutputStream; this Hierarchy
		will be queried for options that affect output
	Added a new class: net.sf.simulatoralive.Hierarchy.HierarchyHelper; it will
		contain helper methods for Hierarchy; currently it contains methods to
		help set up the options useful for affecting XML output (see the
		previous note)
	Added more words that count as true for boolean values; I also shortened
		the isTrue(String) method of Hierarchy; it didn't need all those
		"else if" clauses (an old habit of mine I've started to give up for
		boolean-returning methods)
	AttributeParsers that parse integer types (byte, short, int, long and
		BigInteger) now accept hexidecimal numbers prefixed with "0x" or ending
		with "h"; getting this to work efficiently required the next change, so
		as not to duplicate hex-checking and hex id stripping code in a
		half-dozen methods
	Added a new class: net.sf.simulatoralive.Hierarchy.AttributeCaster; this is
		the type-casting counterpart to AttributeParser and AttributeUnparser,
		except that this purpose was better served by a large number of static
		methods in the class; AttributeCaster is package-private, by the way;
		these type-casting methods are far more rigorous and consistent than the
		older equivalent I shoe-horned into Hierarchy over the years; the old
		type-casting methods from Configuration now live in AttributeCaster and
		serve as the backbone of the class
	Made some internal changes to nearly all the (package-private)
		AttributeParser and AttributeUnparser classes; they're now depending on
		AttributeCaster to handle all the work; this is easier to maintain; the
		parser and unparser classes are now just stubs
	Altered Hierarchy to use AttributeCaster; these changes shaved a significant
		amount of code out of Hierarchy and put it into a class dedicated to the
		task; an overall increase in maintainability
	Clarified the API documentation comments on Hierarchy.commit() and
		Hierarchy.rollback very slightly
	Cleaned up the imports in all files in the net.sf.simulatoralive.hierarchy
		package; no more * imports and they're alphabetized
	Moved construction of the static type-related Maps in Hierarchy to a new
		class: net.sf.simulatoralive.hierarchy.AttributeDefinition; this now
		takes care of defining Hierarchy's types in it's singleton constructor;
		this should make it dead simple to add a new type; just build an
		AttributeParser, an AttributeUnparser, decide on a type string and add a
		line describing it all in AttributeDefinition

2.1.0 Stable (9/14/12)
	Made a very minor fix in Hierarchy that prevents a Hierarchy from being
		wrapped in an immutable or synchronized wrapper multiple times; it was a
		tiny corner case related to wrapping a Hierarchy to make it syncronized
		and then wrapping it to make it immutable; no one would likely ever do
		that, but now a Hierarchy will be synchronized once and made immutable
		once, regardless of the order they're done in and how many times it's
		attempted
	Modified Hierarchy to store character arrays directly, instead of storing
		them as Strings; this should somewhat accelerate the use of character
		arrays as Hierarchy attribute values; the XML format includes these as
		the "char[]" attribute type; single characters are still stored as
		single element character arrays
	Added a missing @throws comment to
		Hierarchy.setAttributeObject(String,Object); it has always thrown a
		NullPointerException if name or obj are null, but I neglected to comment
		on it
	Commented out two methods in Hierarchy: getAttribute(String,int,float) and
		getAttribute(String,int,double); I'm not exactly sure why they were ever
		in there, but they're disabled now; I'll probably remove them from the
		source at some point; probably after I figure out why they were there
	Added a pair of methods to Hierarchy to allow using java.util.BitSet
		instances as attributes; internally, this converts them to and from
		boolean arrays
	Added a pair of methods for sorting insertion-ordered Sets and Maps to
		Configuration
	Added methods to Hierarchy to store and retrieve raw data as byte arrays;
		these methods are intended for storing data that's meaningless to
		represent textually, so these attributes are GZip compressed and Base64
		encoded when stored in an XML file
	Added a pair of utility methods to Hierarchy that provide an InputStream and
		an OutputStream that read or write a raw data attribute
	Added a pair of utility methods to Hierarchy that provide a Reader and a
		Writer that read or write a String attribute; the Reader provided can
		also read directly from a char array or convert any other type into a
		String and then read that

2.0.1 Stable (9/7/12)
	Made a smallish tweak to how HierarchyTreeNode displays attributes; it's now
		displaying things as unencoded Strings, without quotes, but now
		attributes display as a tree node with a single leaf node as a child;
		the child displays the value of the attribute and the parent displays
		the name
	Added API documentation comments to HierarchyTreeNode
	Added API documentation comments to the newer static methods in Hierarchy
	Commented out the deprecated, no-argument constructor in XMLHierarchy; I
		should have done this for the previous release, since I changed the
		package names; in theory no one should be inconvenienced by this
	Fixed a bug in HierarchyTransaction; one of the methods wasn't static, but
		should have been
	Added a few missing static methods to classes in the
		net.sf.simulatoralive.transaction.hierarchy package

2.0.0 Stable (8/31/12)
	First release for the SimulatorAlive sourceforge.net project
	Changed the package names for all classes to start with 
		net.sf.simulatoralive; they now reflect the sourceforge project's name,
		which is something I should have done all along
	Removed several irrelevant, partially complete classes I have no intention
		of ever finishing
	Marked several classes stable that were Alpha and Beta
	Fixed bugs related to output of mal-formed XML files when certain characters
		were in quoted Strings; I was unaware of this bug until I tried to view
		a Hierarchy as XML with firefox and it threw a fit; after a bit of
		investigating, I added a list of characters that shouldn't be used in
		XML files
	Added a pair of new abstract methods to Hierarchy: nodeSet() and
		attributeSet(); these provide an unmodifiable Set view of the names of
		the nodes and attributes, respectively; this required changing all
		concrete extensions of Hierarchy
	The attributes() and nodes() methods of Hierarchy are now concrete, based on
		the new nodeSet() and attributeSet() methods
	Clarified some unclear API documentation that gave me some headaches
	Made ImmutableHierarchy and SyncronizedHierarchy package-private; they've
		been replaced by static methods in Hierarchy; this mirrors the
		Collections API in the java.util package
	Added some error checking to the constructor of DefaultHierarchy; it now
		throws an IllegalArgumentException if main and defaults are the same
		object
	Fixed a lack of checking for null input on the
		addListener(HierarchyListener) method
	Altered DefaultHierarchy, ImmutableHierarchy and SynchronizedHierarchy so
		that they send a new HierarchEvent with the source changed to
		themselves; This should finally prevent any accidental alteration of a
		Hierarchy wrapped by an ImmutableHierarchy
	Made HierarchyEvent final
	Fixed the lack of a removeListener(HierarchyListener) method on several
		Hierarchy-extending classes that needed to override it
	Added a new class: HierarchyTreeNode wraps a Hierarchy and an optional name,
		allowing the Hierarchy to be displayed in a JTree
	Added some static utility methods for storing and loading Collections and
		Maps via a Hierarchy

1.3.1 Beta (3/15/08)
	Fixed an Javadoc comment in XMLHierarchy that referred to the old way it
		functioned before the previous version was released
	Removed the obsolete and package-private display methods; equivalent work
		can be accomplished by the storeToXML(OutputStream) method
	Added a new package: net.jinx.db.file; this package contains classes related
		to a simple binary blob database I'm building, as just about every
		database implementation I've used or read the API docs of does something
		I feel is completely wrong for my needs

1.3.0 Beta (11/10/07)
	Fixed a typo in the Javadoc comment for Hierarchy.commit()
	Added a new class called net.jinx.db.DefaultHierarchy; read it's API docs
		for more information
	Added a new class called net.jinx.db.ImmutableHierarchy; this in an
		immutable wrapper for another Hierarchy
	Added a new class called net.jinx.db.NoRemoveIterator; this is an immutable
		wrapper for java.util.Iterator Objects
	Added a new class called net.jinx.db.SimpleHierarchy; this is a very
		simplistic in-memory Hierarchy with no frills; the commit(), close() and
		rollback() methods are implemented as blank, no-operation methods
	Added a new class called net.jinx.db.MemoryHierarchy; this is a
		SimpleHierarchy sub-class with functional commit() and rollback()
		methods that ssave and restore the Hierarchy's state to an in-memory
		backup copy
	XMLHierarchy is now a sub-class of MemoryHierarchy; rollback() calls should
		be MUCH faster now as reading from disk is no longer required except
		during initialization
	Added a pair of new constructors to XMLHierarchy for building based on File
		objects; the old constructors are now based on these
	Fixed some documentation typos for XMLHierarchy's constructors
	Marked the no argument constructor of XMLHierarchy deprecated; it's been
		replaced by the SimpleHierarchy class
	Added a new class called net.jinx.db.LockingXMLHierarchy; this extension of
		XMLHierarchy creates an additional file and then locks it so that any
		JVM trying to access the files via the same configuration will fail
	Added a new package called net.jinx.db.transaction; this contains classes
		related to wrapping Objects in very database-like veneer; it's all
		pre-alpha code, so I wouldn't suggest using it, but you may find it
		interesting none the less
	Hierarchy now implements Serializable; the only implmentation that won't
		serialize is LockingXMLHierarchy, as it has some members that cannot be
		serialized
	The methods related to XML parsing and storing in Hierarchy have been
		generalized; it's now much easier to add new types; this is implemented
		with a set of immutable Map Objects that contain parsers, translators
		and class to type String mappings; all that must be done is add
		appropriate key-value pairs to these maps at the top of the source file
		and add methods to get and set attributes with those types
	In order to make the above possible, I added two new source files for
		the package-private interfaces AttributeParser and AttributeUnparser;
		each of these files contains multiple instances for all the types that
		need them
	Fixed a subtle error that could pop up when grabbing arrays from a
		Hierarchy; if you asked for the exact type stored in the Hierarchy a
		direct reference was returned, allowing the modification a Hierarchy
		without touching it's methods; these methods are now returning a copy of
		the array; sorry for the slight slow down this causes, but it is
		important for ImmutableHierarchy and the HierarchyListener interface and
		to avoid breaking some of the guarantees of how Hierarchy operates
	Made a small change in all of the arrray handling getAttribute methods that
		will handle arbitrary Number[] instances being stored directly in a
		Hierarchy like primitives; this was handy for the changes related to the
		next comment
	Added new methods to Hierarchy for handling BigDecimal and BigInteger in
		much the same manner as the primitive types
	Added utility methods to handle char and char[] types; these were
		implemented by converting to String Objects, as I don't see the need to
		go to all the effort to deal with the headache for a tiny little
		speed-up on something nobody is likely to use anyway
	Fixed a bug that could cause methods that return primitives to return
		default values instead of a parsed value when converting from a String;
		this may have been happening when numbers were padded with spaces
	Added a new class called net.jinx.db.SynchronizedHierarchy; this wraps
		another Hierarchy in a Thread-safe manner
	SimpleHierarchy and MemoryHierarchy each have a new utility Constructor that
		allows reading in an XML file; don't think this functions like
		XMLHierarchy; they're not persistent

1.2.1 Stable (1/20/07)
	Added some missing Javadoc comments to Hierarchy

1.2.0 Stable (3/3/06)
	Added a new utility method to Hierarchy; getAttribute(String, URL) for
		parsing URLs; I thought it might come in handy
	Added a new utility method to Hierarchy; setAttribute(String, URL) to go
		with the new getAttribute(String, URL) method
	Added two new methods related to loading and storing Hierarchies to/from
		Properties objects; loadFromProperties(Properties) and
		parseFromProperties(Properties)

1.1.0 Stable (10/18/05)
	Added event listener capability to Hierarchy and XMLHierarchy
	Finally moved HierarchyMetalTheme to a source tree intended for gui stuff

1.0.0 Beta (10/17/05)
	Initial release for The Deimos Project; previous versions were for the
		Modeler
	Added direct handling of primitives to Hierarchy and XMLHierarchy; this
		involved a relatively small, but incompatible API change; extensions of
		Hierarchy will now have to implement setAttributeObject(String, Object)
		and getAttributeObject(String) instead of setAttribute(String, String)
		and getAttribute(String); the latter two now have concrete
		implementations in Hierarchy itself
	Added alot of utility methods to Configuration for converting various
		primitive array types into eachother
	Altered the format of the files Hierarchy parses and produces; attributes
		have an extra key/value pair called "type" that designates the primitive
		type for the attribute; if it's missing, then the type is assumed to be
		String; You'll be happy to know that the new format is backwards
		compatible, since all attributes used to be Strings
	These changes should significantly speed up in-memory access of primitive
		data stored in a Hierarchy, since now attributes won't be dynamically
		converted from Strings unless the attribute is typed as a String;
		conversion will happen when written to disk, which may slow things down
		a bit, but overall performance should be improved
	Added a main(String[]) method to XMLHierarchy; it allows you to specify two
		files and the first will be parsed and then written to the second; this
		will let you see whether or not the file is properly formed by comparing
		the results with the original; it will also clean up and properly indent
		the file
	Changed the return value of the removeAttribute(String) method from String
		to Object; this was required to accomodate the fact that Hierarchy can
		store more than just Strings now