RELEASE-NOTES.txt

GIScore Release Notes
---------------------

These are the release notes for the GIScore library. At a minimum, this file
attempts to document changes to the public APIs. This file also provides a
high-level overview of the features added in each release.

This product includes software developed by the JDOM Project (http://www.jdom.org/).

------------------------------------------------------------------------------
Release 2.0.0

Changes

- Packages are now under org.opensextant for the public release
- Local repository references are removed
- Build system is now using gradle in place of ant
- Now uses the built in STaX implementation
- Removed war file, remote implementation, SDE implementation and all ESRI 
ArcObjects dependencies to a separate project for later triage

Notes

- The createJNI task for gradle is not currently working, fix the generated
headers manually if necessary.

------------------------------------------------------------------------------

Release 1.8.3

Changes

New implementation of FileGDB Input and Output based on ESRI's C++
libraries.

Bug fixes:
-Fix to polygon, ring and line handling for filegdb.
-Fix KmlOutputStream to output refreshVisibility + flyToView elements if set in NetworkLink.

Improvements:
-Added additional validation checks in KML handling
-Add checks for whitespace in coordinate tuples and wrong number of points in geometries for KML input
-Added check in KmlInputStream to normalize out of range rotation values same as Google Earth does

------------------------------------------------------------------------------

Release 1.8.1

Maintenance release

Previous versions should have been 1.x.x versions
so new version 0.8.1 is changing baseline to 1.8.1
to reflect major version number.

0.8.0 had some old code included due to migration mixup
from subversion to git repository in Oct 2012.

------------------------------------------------------------------------------

Release 0.8.0

Improvements:

-Added circle support to GeoAtom
-Added support for reading shapefiles from input streams
-Made streaming shapefile reading more extensible

DbfOutputStream
-replaced multiple SimpleDateFormats with custom date parser

Introduced 21 non-compatiable API changes due to replacement of
 java.awt.Color to custom light-weight class of the same name. Some method
 signatures changed from java.awt.Color to the custom class. All caller
 code should only need to change package name in the java.awt.Color import
 to org.mitre.giscore.utils.Color and recompile. This change allows giscore
 to run in restricted environments such as the Google App Engine where
 java.awt.Color is blacklisted.
 
------------------------------------------------------------------------------

Release 0.7.1

This release fixes few Shape/DBF bugs in addition to some improvements to ESRI
Shape file and KML handling.

Bug fixes:

DbfOutputStream
-Correctly write numeric fields with right-justification as per spec
-Change non-floating numeric fields (OID, SHORT, INT) from 'F' field type 
 to 'N' field type.
-Fix large double/floats [formatted length > 34 chars] being truncated and
 values mangled by formatting in exponent notation
    
Improvements:

-Added support for gx:drawOrder to GeometryBase, KmlInputStream, and KmlOutputStream

DbfInputStream
-Numeric fields starting with '*' are considered null
-Added LONG type to SimpleField

DbfOutputStream
-Handle Long values in ShapeOutput as numeric (N) type field with decimal count=0

Schema
-Added entrySet()

------------------------------------------------------------------------------

Release 0.7.0

This release adds support for a new data format: OGC Well-known text (WKT).
Fixed minor bugs along with additional support and improvements to KML handling.
Few minor API changes as cleanup.

-Added new WKTInputStream and WKTOutputStream classes.

-Added support for address and phoneNumber in KmlInputStream and KmlOutputStream

-Added support for non-KML namespace elements in ExtendedData

-Correctly handle namespace declarations in XML elements

-Change XmlOutputStreamBase.formatDouble(double d) from static to instance method
 change formatting from Double.toString() with DecimalFormater instance
 as used by KmlOutputStream. Now rounds-off at 10 decimal places to eliminate
 round-off errors.
 
Common
-added setRegion(Geodetic2DBounds bbox)

KmlInputStream
-Minor fix to allow whitespace before/after listItemType values

KmlMetadataDump
-change containers from Stack to LinkedList so can search from newest to oldest ancestor for inheritance

KmlOutputStream
-updated handleExtendedData() to handle arbitrary XML extended elements
-fix handleLinkElement() to encode whitespace as %20 in URLs

Style
-Added copy constructor

UrlRef
-Updated getInputStream() to retry failed KMZ as KML in case content is mis-categorized

------------------------------------------------------------------------------

Release 0.6.2

This release fixes minor bugs and enhancements in KML handling.

IKml
-add viewRefreshMode and refreshMode enumeration values as constants

GeometryBag
-Adjust all methods that change the geometries list to reset the bbox field (e.g. add(), addAll(), remove(), etc.)
-getCenter() now returns null if no contained geometies has a center point
-Override getBoundingBox() and return null if cannot compute a bounding box

KmlBaseReader
-Added setHttpQuery and setViewFormat to override default query/format parameter values
-Changed default viewFormat default values from 0's to more meaningful values
-Renamed getTrimmedValue() to trimToNull()
-Added trimToEmpty()
-Added getBaseUrl()

KmlReader
-Added isMaxLinkCountExceeded() to flag if limit was reached

KmlInputStream
-Support rotation element for PhotoOverlays
-Allow viewFormat tag in Link to have empty string value (Before empty strings were treated as nulls)
-Support deprecated color element in BalloonStyle

KmlOutputStream
-Add missing roll element for Camera in output
-Output Point and rotation elements for PhotoOverlay

KmlMetaDump
-add check for valid output file names in getWriter()
-added test for absolute/relative styleUrl in Features and StyleMap Pairs

NumberStreamTokenizer
-reimplemented using Apache Harmony project and its implementation
 of java.io.StreamTokenizer. This has Apache vs GPLv2 license.

PhotoOverlay
-add rotation field
-implement readData(), approximatelyEquals(), writeData() methods

Style
-Updated checks in setBalloonStyles()

UrlRef
-Added isAbsoluteUrl() helper method

------------------------------------------------------------------------------

Release 0.6.1

This release fixes minor bugs and enhancements in KML handling.

Circle
-cleanup visit(Circle circle) allowing to draw point if numberCirclePts = 1 or line if n = 2
-added setNumberCirclePoints(int) to set circle point count per instance basis
-rename getNumCirclePoints() to getNumberCirclePoints()

DocumentStart
-Added addNamespace() method

KmlMetaDump
-Added maxLinkCount argument to set limit of recursion when importing networklinks

KmlReader/KmlWriter
-add support for inline Styles within StyleMaps for URL normalization

KmlReader
-Added maxLinkCount field to limit recursion when importing networklinks

KmlOutputStream
-add support for gx:TimeStamp/gx:TimeSpan in LookAt/Camera elements

Line
-Added new constructor with Geodetic2DBounds argument

NetworkLink
add hashCode() + equals()

Point
-add constructor Point(Latitude lat, Longitude lon)

UrlRef
-add explicit check for relative URIs in constructor and throw MalformedURLException
 vs allowing URI.toURL() to throw a Runtime Exception

------------------------------------------------------------------------------

Release 0.6.0

Overhauled how Styles and StyleMaps are handled in KML I/O.
Note giscore 0.6.0 is not fully backward compatible with 0.5.28 with respect to
KML handling due to these changes.

 Previously styles were written before the target feature they are to be children
 of (Feature or ContainerStart) and were queued internally. Externally the order
 of Styles read were reversed from the order in the KML source.

 Now the order of all elements including Styles and StyleMaps is preserved in
 reading in KmlInputStream. Likewise, adding a Style is now done by calling
 setStyle() on a Feature or addStyle() on a ContainerStart element as opposed
 to writing the Style object to the stream immediately before writing the feature
 to the stream.

KmlReader, KmlWriterm KmlInputStream, KmlOutputStream, and KmlMetaDump changed to support
changes in Style handling.

Updated dependency itf-geodesy library to 1.9.23 incorporating numerous bug fixes

AbstractObject
-implement equals(Object obj) + hashCode()

AtomAuthor
-fix in readData() for null values

AtomHeader
-Fixed serialization with changes to readData()

AtomLink
-Fix potential NullpointerException in writeData() if type is null

Circle
-fix error in equals() and hashCode() for null value condition

ContainerStart
-add styles field + getStyles/setStyles/addStyle methods
-implement equals(Object obj) + hashCode()

Feature
-Added style field + getStyle/getStyle methods
-implement equals(Object obj) + hashCode()

GeoAtomInputStream
-fixed bug in readEntry() not setting foreign namespace elements

KmlOutputStream
-Corrected output order for ListStyle and gx:balloonVisibility

Model
-added null values checks

MultiPoint/LinearRing/Polygon
-force private fields to be non-null in default constructor

Overlay
-implement equals(Object obj) + hashCode()

Row
-implement explicit hashCode() rather than using inefficient HashCodeBuilder.reflectionHashCode()

Shape2Kml
-Added this new standalone utilility application

SimpleObjectInputStream
-added readNonNullObjectCollection()

SimpleObjectOutputStream/SimpleObjectInputStream
-Add support for Color as scalar
-Added support for serializing enumeration values

SimpleField
-change field access from package protected to private

Style
-Added readData() + writeData() for serialization

StyleMap
-Added support for inline Styles
-Added readData() + writeData() for serialization
-Added new Pair class used by StyleMap.

XmlOutputStreamBase
-Fixed bug in escapeAttribute() that output attribute name for the value replacing the actual value

------------------------------------------------------------------------------

Release 0.5.28

This release fixes minor bugs and enhancements in KML handling. Also fixes
NullPointerException bugs in two geometry classes.

KmlInputStream
-Fixed parsing drawOrder in GroundOverlay allowing whitespace in value and catching exception for non-numeric values
-Allow '#' prefix in color values as does Google Earth
-Add better handling of HTML markup in name field

KmlReader
-Replace ZipFile with ZipInputStream which is not as strict in validation of zip header fields

KmlOutputStream
-Handle Circle geometry and generate Line/Ring/Poly depending on circle hints types
-Added getNumCirclePoints()
-Corrected output order of elements for ListStyle
-Fix order of gx:balloonVisibility in output

KmlMetaDump
-Fixed bug that aborted scan of directories if failed to open a file
-Fixed parsing tilt in LookAt with non-numeric values

Circle
-Fixed NullPointerException in equals(Circle) if argument was null

Point
-Simplified null check logic forcing "pt" field to always be non-null
-Fixed NullPointerException in equals(Point) if argument was null

------------------------------------------------------------------------------

Release 0.5.27

This release fixes minor bugs and enhancements in KML and Shape file handling.

ShapefileInputStream
-Allow file argument in constructor to be directory or single .shp file

Added getType() to IContainerType interface

Add support for Snippet/snippet in KmlInputStream/KmlOutputStream

Added crossDateLine() to GroundOverlay

Updated KmlOutputStream.handleOverlay() and KmlInputStream.handleLatLonBox
to normalize LatLonBox coords if needed.

KmlMetaDump
- Added checks:
  * Feature uses merged shared/inline Style (info)
  * Feature uses shared Style (info)
  * Shared styles in Folder not allowed [ATC 7] (warning)
  * Shared styles must have 'id' attribute [ATC 7] (warning)
  * StyleUrl must contain '#' with identifier reference
  * GroundOverlay fails to satisfy east > west constraint [ATC 11]
  * GroundOverlay fails to satisfy north > south constraint [ATC 11]
  * GroundOverlay spans -180/+180 longitude line

------------------------------------------------------------------------------

Release 0.5.26

This release fixes minor bugs in KML handling and updated geodesy library with Geodetic3DBounds fixes.

LinearRing
-Fixed LinearRing(Geodetic2DBounds box) to check for 3D bbox and create 3d points accordingly at max elevation height

KmlInputStream
-Handle ArrayIndexOutOfBoundsException in read() such that read gracefully fails

KmlReader
-Added KmlReader(InputStream is, boolean isCompressed, URL baseUrl, Proxy proxy) constr

KmlMetaDump
-added custom log4j Appender to capture warn/errors logged by KML classes and add them to summary of errors/warnings.
-updated checkGeometry() to check Lines, Polygons and LinearRings.
-added check for duplicate consecutive points
-added checks:
 * comma found instead of whitespace between tuples (error)
 * ignore invalid character in coordinate string (error)
 * ignore invalid string in coordinate (error)
 * Line clipped at DateLine (info)
 * Inner rings in Polygon must not overlap with each other (warn)
 * LinearRing must start and end with the same point (error)
 * LinearRing can not self-intersect (warn)
 * Bad poly found, no outer ring (error)

Add support for "open" element on KML input and output for containers
-Added IContainerType with changes to NetworkLink, ContainerStart, KmlInputStream, and KmlOutputStream

XmlInputStream
-Change skipNextElement() accessibility from public to protected

Added java.net.Proxy to UrlRef/KmlReader to proxy URL connections

Updated dependency: itf-geodesy 1.9.14 -> 1.9.16 with Geodetic3DBounds fixes

------------------------------------------------------------------------------

Release 0.5.25

This release fixes minor bugs in KML input/output, Schema, and Polygon point handling.

Polygon
-fix getPoints(). failed if points in "wrong" order.
 Puts outer ring points in clockwise order and inner ring points in ccw order

KmlInputStream
-fix interpreting KML elements as non-kml/foreign elements if kml root element does not declare explicit kml namespace

KmlOutputStream
-Properly escape schema id value in output

UrlRef
-updated isIdentifier() to allow %HH URI-escaping
-added isHexDegit()

Schema
-Update setName() to normalize name value stripping leading/trailing whitespace and not allow blank strings as valid

KmlMetaDump.java
-Add check for suspicious Schema id/name characters to enforce Schema id/name constraints

------------------------------------------------------------------------------

Release 0.5.24

This release primarily introduces cleanup and bug-fixes to KML input/output and some underlying XML handling.

Fixed bug in KmlWriter that did not close all image entries in created KMZ file
creating corrupt ZIP file. Added flag to underlying KmlOutputStream/XmlOutputStreamBase classes.

StyleMap
-add containsKey() method + added NORMAL/HIGHLIGHT constants

KmlInputStream
-Updated StyleMap handling

UrlRef
-Added check in escapeUri() to escape all control chars (ASCII code < 0x20) and extended chars (code >= 0x7f)

------------------------------------------------------------------------------

Release 0.5.23

This release primarily introduces enhancenments and minor bug-fixes to KML input/output
and some underlying XML handling.

General
  * Added ListStyle support to Style/KmlOutputStream/KmlInputStream
  * Update geodesy 1.9.14 using short-cut from Geodetic2DPoint.getLatitude().inDegrees()
    to Geodetic2DPoint.getLatitudeAsDegrees().
  * Add @Nullable/@CheckForNull annotations to methods in GroundOverlay, Overlay, Style, etc.
  * Added getEncoding() to XmlInputStream, KmlInputStream, KmlReader so output stream can have
    correct character encoding if not UTF-8 used

Common
  * Fix setStyleUrl() to auto-fix the url if relative idref and '#' not first character

GISFactory
  * Added encoding (String) as first argument to KML + KMZ type in getOutputStream()
    so can match correct character encoding

KmzOutputStream
  * Added public KmzOutputStream(OutputStream stream, String encoding) constructor

XmlGdbOutputStream
  * Update close() and close streams in finally block to close even if exception thrown

GroundOverlay
  * Added setBoundingBox(Geodetic2DBounds box) to set overlay bounding box from Geodetic2DBounds

Style
  * Change double to Double and boolean to Boolean in field types and associated getters/setters to allow Nullable values.

UrlRef
  * Update User-Agent to Google Earth 5.2 identifier
  * Add new methods: isIdentifier(), isXMLNameCharacter(), isXMLNameStartCharacter()
  * Updated escapeUri() to handle ascii control chars 00-2f and extended 7f-ff

------------------------------------------------------------------------------