In short, you can think of a Map as an ordered list of Layers, where each layer is rendered on top of the previous ones according to the data it contains (the feature source) following certain painting rules (the style).
The map is represented by the MapContext interfaces, which provide methods to manage layers (that is, add, move and remove). You can add a layer by first creating an object implementing the MapLayer interface, or by directly using convenience methods that take either a FeatureSource or a FeatureCollection and a Style object.
You can set an area of interest using the setAreaOfInterest() method, which also sets the CoordinateReferenceSystem (CRS) of the MapContext. Renderers should be able to reproject data coming from another CRS into the MapContext CRS at rendering time. Unfortunately, at the moment, only the j2d.Renderer has the infrastructure to do this, and we also lack support for CoordinateReferenceSystems in the data sources. At present I'm not aware of any that can properly read the CoordinateReferenceSystem from the persistent data store (please also consider that the most common data sources, such as old style shapefiles, do not carry any CRS information).
A MapContext also has some non-geographic information such as a title, an abstract and a set of keywords. These can be used in printing functions or in graphical settings to better describe the map (they are the only metadata available at the moment at the MapContext level).
Applications interested in the MapContext and MapLayer events can listen on the set of interfaces provided, namely:
- PropertyChangeListener for listening to metadata changes;
- MapLayerListListener for listening to changes in the list of layers (order changes, insertion, deletions);
- MapBoundsListener for listening to area of interest or coordinate reference system changes.
As you may have noticed, MapContext and MapLayer are just interfaces: use the DefaultMapContext and DefaultMapLayer default implementation if you don't have fancy needs, or roll your own specialized implementations otherwise.
Example of map creation with layers, feature collection and style.