README FlightGearGardener - Version 03 - as of JAN 18, 2018
===========================================================
1. Purposes
2. Usage and rights
3. Content
4. Release Notes
1. Purposes
===========
The global purpose behind this Application was to use JavaFX to produce (yet another) asynchronous
downloader for FlightGear Terrasync Scenery, a kind of light version of the well known TerraMaster
tool, but based on the DNS/HTTP download principles, and using JavaFX instead of Swing.
This is just a first trial, to be regarded as a reasonably usable output of a coding exercize...
(covering controlled synchronization only for TERRAIN, OBJECTS and AIRPORTS, with additional but
limited support for browsing a Terrasync server and downloading (piecewise!) Building, Models,
Pylons..., pretty anything found there, indeed).
It has evolved as a learning workbench, for me and possibly other Java developers interrested
in geting some grip over things like geographic data handling (although there is no use of
advanced technology like GeoTools)... Considering that the most time-consuming operations are
Network and MMI interactions, considering also the asynchronous (out-of-flight) nature
of this application, design and coding were focused mainly on comfortable use, intuitive
interactions, and readable, reusable internal structures, not maximum speed (using systematically
.dirindex files and SHA-1 signatures is however delivering quite satisfying results).
While certainly not a model of Java OO development (using less than 25 specific classes clearly
points in the direction of a persistent "procedural" bias), and possibly for that reason too,
I see FlightGearGardener also as a (very humble!) celebration of James Goslin's marvelously
clever, robust, expressive, predictable, well-balanced and, all in one, pleasurable creation...
2. Usage and rights
===================
Beyond the java code written specifically for FlightGearGardener, there are only four externaly
sourced stuff:
- the Java API provided by the jdk1.8.0_102 and Netbeans 8.2, of course;
- NaturalEarth Shapefiles (ne_110m_admin_0_countries) :
http://www.naturalearthdata.com/about/terms-of-use/ ;
- Brian Wellington's dnsJava-2.1.7 library :
http://www.dnsjava.org/dnsjava-current/README ;
- Thomas Diewald work on reading ShapeFiles :
http://thomasdiewald.com/blog .
Concerning Thomas Diewald, his work was effectively the main avenue enabling me to understand quickly
how to handle and render ESRI ShapeFiles in Java. Though I eventually did not use his (much more
ambitious and fully engineered) code, it's a pleasure to recognize his seminal impact. Moreover,
his blog is a real delight for those loving computer graphics and algorithmic fancies rendering...
Concerning Brian Wellington's dnsjava, let's mention the following license notice, as requested:
"dnsjava is placed under the BSD license. Several files are also under
additional licenses; see the individual files for details.
Copyright (c) 1999-2005, Brian Wellington
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of the dnsjava project nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
Obviously, FlightGearGardener, being a public-garden hobby, does not provide any more
warranties about anything.
Since human intellectual productions mostly result from encountering, understanding, and
reassembling other human intellectual productions, there is no constraint put on reusing
FlightGearGardener specific code and so keeping the wheels turning, as long as this does not
concur to freedom limitation, ecological or human harm, or commercial profits.
3. Content
==========
The whole thing is split in two subsets:
A. FG_GardenerV0x.zip, which includes the following folders:
- Config
contains a default (empty) config folder, FLIGHTGEARGardener;
- DefaultTerrasync
contains a default (empty) Terrasync folder, to receive downloaded data in case of
"minimal" test configuration. User may select another one in the Application, or change this
default by editing sysContext.xml;
- FG_bin
contains the executable (FlightGearGardener.jar) and a subfolder, lib, containing a set of
seven run_time library jar files.
FG_bin itself may be freely moved or renamed, but all its content MUST be kept unchanged;
- For_Unix and For_Windows
Contains platform-specific files and guides, and Z_Javapps, a folder containing a file
relocation template, z_Launchpad.xml (which also MUST be edited before use);
- ReadMe
contains... short readme files and user guides(this one included);
- Shapefiles
contains the three NaturalEarth shapefiles used for countries projection. Essential for the
earth map rendition;
- ZZ-logs
a default (empty) folder to receive logs in the "minimal" config case... User may change this
default by editing sysContext.xml;
This set is intended for FlightGearGardener users who don't want reading/modifying the java code.
The easiest way to run/test it is to download the zip and "extract here" in your UserHome folder:
this will create a FG_GardenerV0x folder containing all you need to proceed with "minimal"
configuration (see the Install guides for details and the few mandatory changes still to do before
run). Of course customized install is supported, reading further in the same Guides...).
B. Sources, which contains the java source code. Note that to compile those sources, you will
need the libraries grouped in the FG_bin\lib folder found in A. above (and support for
javaFX API, of course, and JAVA JDK 8).
Sources are structured as follows:
- Package gardenAccessMain: includes the .css STYLE, .fxml GUI and the .java MAIN and CTRL files.
As expected, the CTRL file is the "controller", handling all MMI interactions/events, and
MAIN is the javaFX Stage loader;
- Package gardenDrawer: includes objects and methods used to render the ShapeFile data and
display the World projection map. It uses an never shown Canvas, managed excusively internally
to render the Countries borders, then extract images of the needed parts for display.
The first step is always projecting the whole World map in the "Focusing..." Tab, and
waiting mouse clicks somewhere in the map. Such click will define a 46°x46° zone to be used as
the user-selected focus Region; clicking then the "Apply zoom" button will move the user to the
"Downloading..." Tab, where the Region has been rendered as a 1°x1° grid... The user must then
use a Directory chooser to specify her/his selected target Terrasync folder; using this,
FlighGearGardener will paint the grid cells to reflect the sync freshness state, and give access
to the various Action buttons...;
- Package gardenLoader: includes technical agents used for synchronization and downloads;
- Package gardeningObjects: includes a Constant dictionary, GridCellMatrix, TileSpray,
TileSyncStates..., gadgets quite usefull to get the gardening job done;
- Package gardeningThread: objects used to deliver more time-consuming operations in a separate
thread. Note that this is done primarilly to ensure MMI animation, reflecting the process
progres, and avoiding freeze perception: there is NO effort made to support parallel
downloads, for instance - action buttons are in fact disabled till Task conclusion.
4. Release Notes
================
2018-01-19 Version 03
----------------------
- Very limited code changes; mainly devoted to improve usage documentation (See Use Guides) and
better support for Unix platforms startup (dedicated For_xxx folders);
- Technically, the generic initial font has been changed to Verdana, and some font and fields
sizes have been modified to allow for a better Windows-Unix rendition uniformity.
2018-01-03 Version 02
----------------------
- Modified the Notifier Popup locking and a few ancillary libraries; changed the default configuration
directory on Unix systems to comply with XDG Base Directory specs
2017-11-24 Version 01
----------------------
- Added sub-path directories creation for AIRPORTs and isolated file download...
- Added support for Browsing Terrasync repositories with/without filter "Up-to-date"
(Browse OUTDATED/Browse ALL options); added a few messages to help navigation...
