[udig-devel] Any progress in documenting the udig Architecture?

[Jonas Johansson <jojonas@xxxxxxxxx>]

Hi Adrian, I just searched the archives and found your thread about
understanding the UDIG architecture (your email address was hidden so I
send this to the list). I can tell you I am going through exactly the
same thing as you were, at times with the same frustration. I have spent
something like the last week digging into source code to understand how
things fit together, to be able to add a new layer (constructed by my
own features) to the map, which is now finally working.

Since you were at least three weeks before me on this, I a curious, have
you finished any of those architecture diagrams? I am thinking that if
there is some Wiki somewhere maybe I could also contribute with some
docs from a newbie developer perspective on concepts that I had trouble
understanding when starting udigging.

Jonas

Re: [udig-devel] UDIG Architecture
Adrian Custer
Fri, 03 Mar 2006 02:00:50 -0800


Hey All,

On Wed, 2006-03-01 at 13:02 +0200, Jody Garnett wrote:
> Adrian I enjoyed your email
> and wondered where in the programers guide it could go? Before or after 
> we introduce the concepts you talk about? Perhaps it could be added as part
> of the Overview? How does "4 Guided Tour" sound?

You mean Programer's Guide 1.4? Great. Let's work on that. If you want
it done quickly then we ought to schedule a doc irc afternoon or two
(i.e. one to get started and one to finish). The current problem is that
I see the lack of documentation pretty clearly (i.e. what's needed) but
in order to solve this on my own, it is taking me a huge amount of time
to figure out the various code bases so I'm making slow, unsteady
progress. I realize, of course, that this is not a priority for you all
but unfortunately, I suspect this is a key stumbling block. To code
effectively on uDig I see as needed:

      * A good understanding of GIS'es an how they work
      * A grasp of the terminology used in the uDig/Geotools stack
      * A grasp of Java/C/some programming languge
      * A grasp of the eclipse IDE
      * An understanding of the Architecture

at least that's what I'm working on acquiring.


Three core elements are needed for explaining the uDig architecture



1) A scalable architecture diagram:

There are a number of useful schematic diagrams of udig and geotools,
for example, the diagrams included in the slide show that was posted to
the mailing list (whose name I forgot because I just deleted the file
yesterday). However, these diagrams are very primitive: they don't, for
example, get used in a more detailed explanation of what classes get
called in different situations. I hope to develop eventually a diagram
that scales from the 

  Hardware || JVM / Clibs  || Geotools / Eclipse || uDig

to a diagram where each uDig and Geotools package can be viewed as a
block with an API used to access that block and an internal example. I
grant this is a long term vision but something I'm working on for my own
sanity in this way complex uDig world. E.g.

  **************************************************************
  * N  *       * Api interface 1     * Api interface 2 ...     *
  * A  *       *************************************************
  * M  *                                                       *
  * E  *        Code Examples ...                              *
  *    *                                                       *
  **************************************************************

Once I can make a single clean example, I'll convert my hand sketches to
SVG with inkscape and spam the list.





2) A diagram of the data model of a uDig in a frozen state:

uDig follows the model, view, controller split. I would like a diagram
of each for a uDig frozen at the moment when it has 2 Projects open, one
with 5 maps, with one map having n different layers (possibly one of
each type of IGeoResource which uDig provides. 

The idea is to have a hypothetical tree of how to access each of the
components in the model (data) hierarchy, in the view hierarchy, and in
the controller hierarchy. Since there are static methods provided to
access the root of each hierarchy, the three trees would provide users
with a cannonical example for accessing each piece of a running uDig. 


        For example, right now I'm trying to build a uDig layer from
        scratch. Now I have to figure out where the CRS (or SRS, I'm not
        yet sure of the semantic distinction) information is held. I can
        imagine that the map must have its own and each feature (or
        maybe geometry) has its own or maybe all the features in a
        datasource always share the same. I.e. I know that the CRS's
        must be defined at various levels but we don't yet have a
        diagram that shows:
        
                This example is off the top of my head. It's not worth
                my time right now to get accurate. Think of it as an
                example of some other system.
                
                
           uDigMap:
            --- getCRS   ---> The Map's CRS
        
             --- resolve IGeoResource 1 ---> Feature 1
                                              |---> .getCRS()
             --- resolve IGeoResource 2 ---> Feature 2




3) A set of examples of how to construct each element.

Access is one thing, but construction is another. Once we have diagrams
for accessing an example of each piece in uDig we then need an example
of how to *build* from scratch each of the pieces. The building from
scratch is a second way of sharing the model with new programmer's.
While the "resolve" idea is quite simple in the resolution direction,
I'm still quite puzzled about what's going on when we create a new
coordinate, geometry, feature, datastore (magic happens here)
IGeoResource eventhough I can now display my buffered points in a map. 

For example, I suspect the FAQ "How do I build a Layer programatically"
is exactly this question and is *not* answered at all by the current
answer. For me the question is "how do I start with java doubles and
build up the pieces so I end up drawing a georeferenced map, say a
triangle with vertices in Paris, London and Moscow?" I'd like to create
a really well commented file that explains with a full paragraph each
step of the process, and ideally that then gets expanded into examples
that do each step slightly differently.






For a good documentation stack, I suspect we should have these three
elements: a scaleable architecture diagram, an example of each M/V/C
tree, an example of building each component. I suspect that getting that
into one's head is the precursor to being effective at all in uDig
development (along with understanding well how the eclipse IDE works and
where each of the ten million preferences actually hangs out).
Unfortunately, without yet knowing this and having it in *my* head, I
can't sit down and do the work to make the diagrams. 


Okay, back to trying to figure out uDig so I can write some docs for it
and start developing the analytic components.


All the best,

adrian