it.tidalwave.geo.viewer.package-info Maven / Gradle / Ivy

Go to download

/***********************************************************************************************************************
 *
 * forceTen - open source geography
 * Copyright (C) 2007-2012 by Tidalwave s.a.s. (http://www.tidalwave.it)
 *
 ***********************************************************************************************************************
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
 * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations under the License.
 *
 ***********************************************************************************************************************
 *
 * WWW: http://forceten.tidalwave.it
 * SCM: https://bitbucket.org/tidalwave/forceten-src
 *
 **********************************************************************************************************************/
/***********************************************************************************************************************
 *
 * This package provides a visual component for rendering 2D and 3D representations of geographic areas.
 *
 * 
 *
 * This component does not expose a single interface for services; instead, it works as a factory where specific
 * services can be looked up:
 *
 * 
 * GeoViewerPresentation geoViewerPresentation = GeoViewerPresentation.Locator.findGeoViewerPresentation();
 * GeoViewManager geoViewerManager = geoViewerPresentation.getLookup().lookup(GeoViewManager.class);
 * GeoViewProviderManager geoViewProviderManager = geoViewerPresentation.getLookup().lookup(GeoViewProviderManager.class);
 * FeatureManager featureManager = geoViewerPresentation.getLookup().lookup(FeatureManager.class);
 * 
 *
 * The three exposed services are:
 *
 * 
 * {@link GeoViewManager}: it allows operations such as fitting the view to render the given {@link Coordinate}s
 *     etc.
 * {@link GeoViewProviderManager}: it allows to change the data provider (e.g. Microsoft Virtual Earth,
 *     OpenStreetMap) and the view mode (e.g. map, satellite, etc...).
 * {@link FeatureManager}: it allows to add and remove features on a view.
 * 
 * 
 *
 * 
Injectable roles
 *
 * The implementation of this component is delegated to a set of small and cohese classes named "roles". Each
 * one has got a single reponsibility and usually can be replaced independently of the others. Each role has a
 * symbolic name, which is part of the public API, and an implementation class.

 * Most roles have a default implementation; some are mandatory (i.e. their absence breaks the
 * {@code GeoViewerPresentation}}, while others are optional and can be added by the programmer.
 *
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 *
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 *
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 *
 * 
 * 
 * 
 * 
 * 
 * 
 * Role Description Implementation class Description
{@code CacheLocationProvider}
(mandatory) Provides the path of a folder where a cache of geographical data (e.g. tiles). default The cache is under $HOME/.ForceTen/cache
custom roles Can be implemented by subclassing
 *     {@link it.tidalwave.geo.viewer.role.CacheLocationProvider CacheLocationProvider}.
 * 
{@code InitialLocationProvider}
(mandatory) Provides the initial coordinate where the geographic view will be centered at. {@link it.tidalwave.geo.viewer.role.ZeroZeroInitialLocationProvider ZeroZeroInitialLocationProvider}
default The initial location is at coordinate (0; 0)
custom roles Can be implemented by subclassing
 *     {@link it.tidalwave.geo.viewer.role.InitialLocationProvider InitialLocationProvider}.
 * 
{@code UI}
(mandatory) Provides the visual component. While it is obvious that such a component renders the geographical
 *                 view, this role can be customized to add controls in different places. default The visual component include a toolbar at the bottom of the UI with controls for selecting the
 *     {@link GeoViewProviderManager}, the rendering mode, a customizable button bar and a label with renders the
 *     coordinates under the current mouse position.
 * 
custom roles Can be implemented by subclassing
 *     {@link it.tidalwave.geo.viewer.role.GeoViewerUI GeoViewerUI}.
 * 
{@code ContextListener}
(optional) Listens for the {@link org.netbeans.platformx.eventbus.api.EventBus EventBus} and fits the
 *     geographical view when a {@link it.tidalwave.geo.geocoding.GeoEntitySet GeoEntitySet} or a
 *     {@link it.tidalwave.geo.Sector Sector} is published. 
 * 

 *
 *
 * Customization and configuration
 *
 * Configuration is performed by means of {@code layer.xml}. The following is the default configuration of
 * {@code GeoViewerPresentation}:
 *
 *  * <?xml version="1.0" encoding="UTF-8"?>
 * <!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd">
 * <filesystem>
 *     <folder name="Roles">
 *         <folder name="it.tidalwave.geo.explorer.GeoViewerPresentation">
 *             <file name="GeoViewProviderManager.instance">
 *                 ...
 *             </file>
 *             <file name="GeoViewManager.instance">
 *                 ...
 *             </file>
 *             <file name="InitialLocationProvider.instance">
 *                 ...
 *             </file>
 *             <file name="FeatureManager.instance">
 *                 ...
 *             </file>
 *             <file name="ContextListener.instance">
 *                 ...
 *             </file>
 *         </folder>
 *     </folder>
 * ...
 * </filesystem>
 * 
 *
 * In order to configure {@code GeoViewerPresentation} you need to create a specific NetBeans Platform module with
 * a dependency on this module and a {@code layer.xml}.
 * To replace a default role, the relevant definition must be overridden. For instance, this configuration replaces
 * the "(0;0) initial location provider" strategy with another:
 *
 *  * <?xml version="1.0" encoding="UTF-8"?>
 * <!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd">
 * <filesystem>
 *     <folder name="Roles">
 *         <folder name="it.tidalwave.geo.explorer.GeoViewerPresentation">
 *             <file name="InitialLocationProvider.instance">
 *                 <attr name="instanceClass" stringvalue="my.own.InitialLocationProvider"/>
 *             </file>
 *         </folder>
 *     </folder>
 * </filesystem>
 * 
 *
 * It is also possible to disable a default role without replacing it; the following configuration disables the
 * "context listener" (for instance because you want to manually control the geographical view):
 *
 *  * <?xml version="1.0" encoding="UTF-8"?>
 * <!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd">
 * <filesystem>
 *     <folder name="Roles">
 *         <folder name="it.tidalwave.geo.explorer.GeoViewerPresentation">
 *             <file name="ContextListener.instance_hidden"/>
 *         </folder>
 *     </folder>
 * </filesystem>
 * 
 *
 * Last but not least, it is also possible to add new roles:
 *
 *  * <?xml version="1.0" encoding="UTF-8"?>
 * <!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd">
 * <filesystem>
 *     <folder name="Roles">
 *         <folder name="it.tidalwave.geo.explorer.GeoViewerPresentation">
 *             <file name="MyNewRole.instance">
 *                 <attr name="instanceClass" stringvalue="my.newrole.Implementation"/>
 *             </file>
 *         </folder>
 *     </folder>
 * </filesystem>
 * 
 *
 *
 * Default state
 *
 * This component is placed by default in the "center" mode and it's not set visible by default. If you want to be
 * visible by default, use this customization fragment of {@code layer.xml}:
 *
 *  * <?xml version="1.0" encoding="UTF-8"?>
 * <!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd">
 * <filesystem>
 *     <folder name="Windows2">
 *         <folder name="Modes">
 *             <folder name="center">
 *                 <file name="it.tidalwave.geo.viewer.GeoViewerPresentation.wstcref" url="GeoViewerPresentationWstcref.xml"/>
 *             </folder>
 *         </folder>
 *     </folder>
 * </filesystem>
 * 
 *
 * with {@code GeoViewerPresentationWstcref.xml} being:
 *
 *  * <?xml version="1.0" encoding="UTF-8"?>
 * <!DOCTYPE tc-ref PUBLIC "-//NetBeans//DTD Top Component in Mode Properties 2.0//EN" "http://www.netbeans.org/dtds/tc-ref2_0.dtd">
 * <tc-ref version="2.0" >
 *     <module name="it.tidalwave.geo.viewer" spec="1.0"/>
 *     <tc-id id="it.tidalwave.geo.viewer.GeoViewerPresentation"/>
 *     <state opened="true"/>
 * </tc-ref>
 * 
 *
 *
 * Predefined actions
 *
 * An action to toggle the visibility status of the {@link GeoViewerPresentation} is automatically installed under the
 * "Window" menu. The name of the file representing the action, that can be used to customize the position or remove the
 * action completely, is
 *
 *  * "Actions/Window/it-tidalwave-geo-viewer-impl-action-GeoViewerAction.instance"
 * 
 *
 * @author  Fabrizio Giudici
 * @version $Id$
 *
 **********************************************************************************************************************/
package it.tidalwave.geo.viewer;

Role	Description	Implementation class	Description
{@code CacheLocationProvider} (mandatory)	Provides the path of a folder where a cache of geographical data (e.g. tiles).	default	The cache is under $HOME/.ForceTen/cache
{@code CacheLocationProvider} (mandatory)		custom roles	Can be implemented by subclassing * {@link it.tidalwave.geo.viewer.role.CacheLocationProvider CacheLocationProvider}. *
{@code InitialLocationProvider} (mandatory)	Provides the initial coordinate where the geographic view will be centered at.	{@link it.tidalwave.geo.viewer.role.ZeroZeroInitialLocationProvider ZeroZeroInitialLocationProvider} default	The initial location is at coordinate (0; 0)
{@code InitialLocationProvider} (mandatory)		custom roles	Can be implemented by subclassing * {@link it.tidalwave.geo.viewer.role.InitialLocationProvider InitialLocationProvider}. *
{@code UI} (mandatory)	Provides the visual component. While it is obvious that such a component renders the geographical * view, this role can be customized to add controls in different places.	default	The visual component include a toolbar at the bottom of the UI with controls for selecting the * {@link GeoViewProviderManager}, the rendering mode, a customizable button bar and a label with renders the * coordinates under the current mouse position. *
{@code UI} (mandatory)		custom roles	Can be implemented by subclassing * {@link it.tidalwave.geo.viewer.role.GeoViewerUI GeoViewerUI}. *
{@code ContextListener} (optional)	Listens for the {@link org.netbeans.platformx.eventbus.api.EventBus EventBus} and fits the * geographical view when a {@link it.tidalwave.geo.geocoding.GeoEntitySet GeoEntitySet} or a * {@link it.tidalwave.geo.Sector Sector} is published.