Hello Adam
To make a large library more accessible to neogeographers, maybe we
would need to hide lot of methods and classes in order to keep only the
most important one visible in the javadoc. A lot of classes are internal
mechanics from neogeographers perspective, and would become useful
public API only for more advanced users. However we face two difficulties:
* I'm not aware of any way in current Javadoc technology to flag a
method or class as "advanced API" to be show only when the user
browse the Javadoc in "advanced" mode. I think that such
functionality is under consideration at Oracle, but I don't know
if/when it would appear.
* It is difficult to define what is the "core API" to show to
neogeographers. For example the ISO 19115 standard (metadata), which
defines about 100 classes, tried in its 2003 version to define a
"core metadata" profile with only the few most important classes.
But in their 2013 revision, they are removing this core profile. The
reason is that everyone has a different opinion of what "core" is.
Nevertheless the need is still present and other peoples have expressed
it. When OGC accepted GeoAPI 3.0.0 as a standard, the OGC Architecture
Board (OAB) told us that for the next GeoAPI release (3.1), they will
require us to define a "core" part of that API. This is one area where
I'm going to need help on the GeoAPI side: among the 271 classes or
interfaces in GeoAPI 3.0.0, which one should be considered "core"? That
would define indirectly which SIS classes would be considered core API.
But even if we define core API, we are still facing the problem of how
to hide non-core API from javadoc. I have no technical solution to that
question yet... (but I have hope that JDK9 will help us - note that it
doesn't mean that users have to use JDK9; we would just use JDK9 for
generating the javadoc).
On the question about roadmap toward something usable (WMS or desktop
application), I have to admit that the classes committed up to date are
of little direct use in the short term. To make a WMS, we need a
renderer engine, which needs geometry objects, which need referencing
framework, which need metadata... If we take a short-cut, for example by
omitting the referencing framework for now, I find difficult to
reintroduce referencing awareness in existing code later. We are facing
a similar situation in our existing WMS server: it doesn't behave well
with data crossing the anti-meridian. We have made some attempts to fix
that problem in existing code, but the problem spread in every corners
of the libraries (we have to check every places where an Envelope is
used). This is one example of goal which seem easier to address from the
beginning of a project than to try to fix in existing code.
So it is difficult for me to give a firm roadmap for WMS... The code
exists, but I would like to commit clean code to SIS with known issues
solved...
In the last week I worked on relatively minor secondary classes (Ranges)
because I'm facing a problem with the more important classes (XML
marshalling) for which I didn't found a solution yet: there is
apparently no way to have good control on the prefixes used in XML
documents other than sub-classing the
com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper, which is not
public API. This is what we did in Geotk, but I'm not sure it is
acceptable solution for Apache SIS. I can elaborate more in a separated
thread (but I need to write a test case first for clarifying the
issue...). But admittedly I should focus more on trying to solve this
blocking issue.
Regards,
Martin
