ilog.views.sdm.renderer.maps

Class IlvMapRenderer

java.lang.Object

ilog.views.sdm.renderer.IlvSDMRenderer

ilog.views.sdm.renderer.IlvFilterSDMRenderer

ilog.views.sdm.renderer.maps.IlvMapRenderer

All Implemented Interfaces:

Serializable

public class IlvMapRenderer
extends IlvFilterSDMRenderer

The class IlvMapRenderer is a filtering renderer that displays a background map behind the nodes and the links of the grapher.

The map is specified as the URL of a Rogue Wave JViews .ivl file that will be loaded into the grapher associated with the SDM engine. This .ivl file can contain a vectorial map, one or more bitmaps, or the definition of one or more "load-on-demand" layers that will load the map according to the visible part of the grapher.

The map renderer can be initialized very simply in the style sheet using a declaration like:

 SDM {
   Map : "maps/world.ivl";
 }
 

The map file must contain the projection information corresponding to the map. The projection will be used by the renderer to place the SDM nodes automatically at the correct location depending on the values of their "latitude" and "longitude" properties.

The "latitude" and "longitude" properties can be defined directly in the SDM data model, or they can be defined in the style sheet. For example, if the nodes of your data model have properties named "LAT" and "LONG" instead of "latitude" and "longitude", you must add the following declarations in the style sheet:

 node {
   latitude : "@LAT";
   longitude : "@LONG";
 }
 

The latitude and longitude can be specified in several formats:

• As a floating-point value, in which case the value is the latitude or longitude expressed in radians.
• As a string of the form xxDxx'xx"L, where L is one of the following: N, S, E or W. The string will be converted using the method IlvProjectionUtil.DMSToRadian(java.lang.String).
• As a string matching one of the formats registered using the method addLatitudeLongitudeFormat(java.lang.String, boolean).

For example:

  <node id="Quebec">
    <property name="name">Quebec</property>
    <property name="longitude">70D59'W</property>
    <property name="latitude">46D49'N</property>
  </node>
 

Or:

  <node id="Quebec">
    <property name="name">Quebec</property>
    <property name="longitude">-1.2389</property>
    <property name="latitude">0.8171</property>
  </node>
 

Since:

JViews 4.0

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static String	LATITUDE_PROPERTY LATITUDE_PROPERTY is the name used for the latitude property.
static String	LONGITUDE_PROPERTY LONGITUDE_PROPERTY is the name used for the longitude property.
static String	X_PROPERTY X_PROPERTY is the name used for the x property, i.e. the x coordinate of the symbol on the grapher, in the KERNEL system.
static String	Y_PROPERTY Y_PROPERTY is the name used for the y property, i.e. the y coordinate of the symbol on the grapher, in the KERNEL system.

Fields inherited from class ilog.views.sdm.renderer.IlvFilterSDMRenderer

_renderer

Fields inherited from class ilog.views.sdm.renderer.IlvSDMRenderer

PSEUDOCLASS_PREFIX

Constructor Summary

Constructors

Constructor and Description
IlvMapRenderer() Creates a new symbol renderer with a null filtered renderer.
IlvMapRenderer(IlvSDMRenderer renderer) Creates a new symbol renderer for a specified filtered renderer.

Method Summary

Modifier and Type	Method and Description
static void	addLatitudeLongitudeFormat(String format, boolean latitude) Registers a new format for converting strings to latitudes or longitudes.
IlvRect	computeBBox(IlvSDMEngine engine, IlvManagerView view, IlvTransformer t) This method calls the filtered renderer's computeBBox method.
static double	convertLatLong(Object value, boolean latitude) Utility to convert an SDM value to either a latitude or longitude.
IlvGraphic	createLinkGraphic(IlvSDMEngine engine, Object link, IlvGraphic from, IlvGraphic to) This method simply calls the createLinkGraphic method of the filtered renderer.
IlvGraphic	createNodeGraphic(IlvSDMEngine engine, Object node) This method simply calls the createNodeGraphic method of the filtered renderer.
Object	getGraphicProperty(IlvSDMEngine engine, Object object, String property, String[] pseudoClass, Class targetClass) This method is overridden to handle requests for the "x" and "y" properties.
static IlvMapRenderer	getInstance(IlvSDMEngine engine) Convenient function to get the IlvMapRenderer instance which belongs to the specified SDM engine.
String	getMap() Returns the name of the map file displayed.
String	getParameter() This method calls getMap().
IlvRect	getRegionOfInterest() Returns the "region of interest" on which the SDM view should be centered.
double	getRegionOfInterestMargin() Returns the margin that is left around the objects when the region of interest is computed automatically.
boolean	isAutoRegionOfInterest() Indicates whether the automatic computation of the region of interest is enabled.
boolean	isFitToContentsAllowed() Returns whether fitToContent() is performed during PrepareRendering() processing.
boolean	isHideInvalidNodesAndLinks() Indicates whether or not nodes that are not within the limits tolerated by the map projection will be hidden.
boolean	isUsingThreads() Indicates whether the map read should use threads to load images and/or map data sources.
void	prepareRendering(IlvSDMEngine engine) Loads the map file into the grapher associated with the SDM engine.
void	propertiesChanged(IlvSDMEngine engine, Object object, Collection<String> propertyNames, IlvGraphic graphic) Overridden methods for performance improvements.
void	removeAll(IlvSDMEngine engine) Removes all the layers contained in the map file.
void	setAutoRegionOfInterest(boolean auto) Enables or disables the automatic computation of the region of interest from the position of the objects contained in the SDM data model.
void	setEngine(IlvSDMEngine engine) Sets the IlvSDMEngine instance that has created this renderer.
void	setFitToContentsAllowed(boolean activated) If true, PrepareRendering() performs a fitToContents().
void	setHideInvalidNodesAndLinks(boolean hideInvalidNodesAndLinks) Indicates whether or not nodes that are not within the limits tolerated by the map projection will be hidden.
void	setMap(String map) Sets the name of the map file to display.
void	setParameter(String parameter) This method calls setMap(java.lang.String).
void	setRegionOfInterest(IlvRect regionOfInterest) Sets the "region of interest" on which the SDM view should be centered and zoomed.
void	setRegionOfInterestMargin(double percent) Sets the margin that is left around the objects when the region of interest is computed automatically.
void	setUsingThreads(boolean usingThreads) Determines whether the map read should use threads to load images and/or map data sources.
void	updateObjectProperties(IlvSDMEngine engine, Object object, String property, Object value, String[] pseudoClasses) This method updates the latitude and longitude properties of an object when its corresponding graphic object has been moved in the grapher.

Methods inherited from class ilog.views.sdm.renderer.IlvFilterSDMRenderer

addLinkGraphic, addNodeGraphic, customize, getEncapsulatedGraphic, getFilteredRenderer, getLinkConnectionRectangle, linkGraphicAdded, moveResizeNodeGraphic, nodeGraphicAdded, nodeGraphicBBoxChanged, processServerAction, removeLinkGraphic, removeNodeGraphic, renderingDone, setFilteredRenderer

Methods inherited from class ilog.views.sdm.renderer.IlvSDMRenderer

addViewListeners, callMoveResizeNodeGraphic, convert, convert, getAlias, getAuxiliaryBean, getAuxiliaryBeans, getEngine, getLinkConnectionRectangle, getLocation, needsViewListeners, propertyChanged, removeViewListeners, setAlias, setLayerName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LONGITUDE_PROPERTY

public static String LONGITUDE_PROPERTY

LONGITUDE_PROPERTY is the name used for the longitude property.

LATITUDE_PROPERTY

public static String LATITUDE_PROPERTY

LATITUDE_PROPERTY is the name used for the latitude property.

X_PROPERTY

public static String X_PROPERTY

X_PROPERTY is the name used for the x property, i.e. the x coordinate of the symbol on the grapher, in the KERNEL system.

Y_PROPERTY

public static String Y_PROPERTY

Y_PROPERTY is the name used for the y property, i.e. the y coordinate of the symbol on the grapher, in the KERNEL system.

Constructor Detail

IlvMapRenderer

public IlvMapRenderer(IlvSDMRenderer renderer)

Creates a new symbol renderer for a specified filtered renderer.

Parameters:

renderer - The filtered renderer.

IlvMapRenderer

public IlvMapRenderer()

Creates a new symbol renderer with a null filtered renderer.

Method Detail

prepareRendering

public void prepareRendering(IlvSDMEngine engine)

Loads the map file into the grapher associated with the SDM engine.

Overrides:

prepareRendering in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine.

removeAll

public void removeAll(IlvSDMEngine engine)

Removes all the layers contained in the map file.

Overrides:

removeAll in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine.

getGraphicProperty

public Object getGraphicProperty(IlvSDMEngine engine,
                                 Object object,
                                 String property,
                                 String[] pseudoClass,
                                 Class targetClass)

This method is overridden to handle requests for the "x" and "y" properties.

When these properties are requested, the method reads the values of the LATITUDE_PROPERTY and LONGITUDE_PROPERTY properties for the node, projects them using the projection contained in the map file, and returns the projected coordinates.

Overrides:

getGraphicProperty in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine.

object - The data object that is being rendered.

property - The name of the graphic property.

pseudoClass - The pseudo-class of the object. This parameter can be null.

targetClass - The class of the object on which the property will be set. The method can introspect the class to determine the type of the property, and convert the value if necessary. If this argument is null, the property should be returned without conversion.

Returns:

The value of a property used to render an object graphically.

propertiesChanged

public void propertiesChanged(IlvSDMEngine engine,
                              Object object,
                              Collection<String> propertyNames,
                              IlvGraphic graphic)

Overridden methods for performance improvements.

Overrides:

propertiesChanged in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine associated with the grapher in which the graphic object is displayed.

object - The data object whose property has changed.

propertyNames - The names of the properties that have been modified.

graphic - The graphic object associated with object.

See Also:

IlvFilterSDMRenderer.propertiesChanged(ilog.views.sdm.IlvSDMEngine, java.lang.Object, java.util.Collection<java.lang.String>, ilog.views.IlvGraphic)

updateObjectProperties

public void updateObjectProperties(IlvSDMEngine engine,
                                   Object object,
                                   String property,
                                   Object value,
                                   String[] pseudoClasses)

This method updates the latitude and longitude properties of an object when its corresponding graphic object has been moved in the grapher.

Basically, this method does the inverse job of getGraphicProperty(ilog.views.sdm.IlvSDMEngine, java.lang.Object, java.lang.String, java.lang.String[], java.lang.Class). It applies the inverse projection to the x and y coordinates, and updates the latitude and longitude properties of the data object with the resulting values.

Overrides:

updateObjectProperties in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine.

object - The data object.

property - The name of the graphic property.

value - The new value of the property.

pseudoClasses - The pseudo-classes of the objects. This parameter can be null.

convertLatLong

public static double convertLatLong(Object value,
                                    boolean latitude)
                             throws IlvConvertException

Utility to convert an SDM value to either a latitude or longitude.

Parameters:

value - value of the property (usually retrieved with IlvSDMNode.getProperty(String)).

latitude - true to decode the value as a latitude.

Returns:

the value of the property

Throws:

IlvConvertException - if the property cannot be decoded.

setMap

public void setMap(String map)

Sets the name of the map file to display.

Parameters:

map - A string containing the URL of an .ivl file containing the cartographic information. The map file must contain the definition of a projection.

getMap

public String getMap()

Returns the name of the map file displayed.

Returns:

Returns the name of the map file displayed.

setRegionOfInterest

public void setRegionOfInterest(IlvRect regionOfInterest)

Sets the "region of interest" on which the SDM view should be centered and zoomed. The region of interest is especially useful when the map is a "load-on-demand" map (of the world, for example), and you want to display a particular region of the map (for example, the United States).

The region of interest can be computed automatically to fit the position of the objects contained in the SDM data model, by calling setAutoRegionOfInterest(true).

The default region of interest is null, which means that the view will display the whole map.

Parameters:

regionOfInterest - The new region of interest, in manager coordinates.

Since:

JViews 5.0

See Also:

setAutoRegionOfInterest(boolean)

getRegionOfInterest

public IlvRect getRegionOfInterest()

Returns the "region of interest" on which the SDM view should be centered.

Returns:

the region of interest.

Since:

JViews 5.0

See Also:

setRegionOfInterest(ilog.views.IlvRect)

setAutoRegionOfInterest

public void setAutoRegionOfInterest(boolean auto)

Enables or disables the automatic computation of the region of interest from the position of the objects contained in the SDM data model.

By default, the automatic computation of the region of interest is disabled.

Parameters:

auto - If true, the region of interest will be computed to fit the bounding rectangles of all the objects of the SDM data model. If this parameter is false, the region of interest is left unchanged.

Since:

JViews 5.0

See Also:

setRegionOfInterest(ilog.views.IlvRect)

isAutoRegionOfInterest

public boolean isAutoRegionOfInterest()

Indicates whether the automatic computation of the region of interest is enabled.

Returns:

true if computation is enabled.

Since:

JViews 5.0

See Also:

setAutoRegionOfInterest(boolean)

setRegionOfInterestMargin

public void setRegionOfInterestMargin(double percent)

Sets the margin that is left around the objects when the region of interest is computed automatically. The margin is expressed as a percentage of the bounding rectangle of all the objects. For example, if the margin is 10, the region of interest will be 10% bigger than the bounding rectangle of all the objects.
The default margin percentage is 5.

Parameters:

percent - The new margin, expressed as a percentage of the bounding rectangle of all the objects.

Since:

JViews 5.0

getRegionOfInterestMargin

public double getRegionOfInterestMargin()

Returns the margin that is left around the objects when the region of interest is computed automatically.

Returns:

the margin around objects.

Since:

JViews 5.0

See Also:

setRegionOfInterestMargin(double)

computeBBox

public IlvRect computeBBox(IlvSDMEngine engine,
                           IlvManagerView view,
                           IlvTransformer t)

This method calls the filtered renderer's computeBBox method.

Overrides:

computeBBox in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine.

view - The manager view for which the bounding rectangle is computed.

t - The transformer used to compute the bbox. A null value is equivalent to an identity transformer.

Returns:

The resulting rectangle.

See Also:

IlvFilterSDMRenderer.computeBBox(ilog.views.sdm.IlvSDMEngine, ilog.views.IlvManagerView, ilog.views.IlvTransformer)

addLatitudeLongitudeFormat

public static void addLatitudeLongitudeFormat(String format,
                                              boolean latitude)

Registers a new format for converting strings to latitudes or longitudes.

The format string must contain one sequence of each of the characters d (for degree), m (for minutes), and s (for seconds). Optionally, the format may contain one of the characters N, S, E and W. The string is converted to a negative latitude or longitude if it contains the characters S or W, or if it starts with a - (minus) character.

A string can be converted using a format only if the string has exactly the same length as the format. The sequences of d, s and m characters must match a sequence of the same length of decimal digits. All other characters in the format must match exactly the character at the same position in the string, including the N, S, E, W and - (minus) characters.

For example, the format "dddmmssW" will match the string "1113902W", but will not match "952700W" because the number of digits does not fit.

The following set of formats are pre-registered:

• "dddmmssN"
• "dddmmssS"
• "dddmmssE"
• "dddmmssW"
• "ddmmssN"
• "ddmmssS"
• "ddmmssE"
• "ddmmssW"

Parameters:

format - The new format to register.

latitude - If true, the format will be used to convert strings to latitudes, otherwise the format will be used to convert strings to longitudes.

Since:

JViews 6.0

isFitToContentsAllowed

public boolean isFitToContentsAllowed()

Returns whether fitToContent() is performed during PrepareRendering() processing.

Returns:

whether fitToContent() is performed.

Since:

JViews 7.5

setFitToContentsAllowed

public void setFitToContentsAllowed(boolean activated)

If true, PrepareRendering() performs a fitToContents(). Default is true.

Parameters:

activated - the new value

Since:

JViews 7.5

setParameter

public void setParameter(String parameter)

This method calls setMap(java.lang.String).

Overrides:

setParameter in class IlvSDMRenderer

Parameters:

parameter - The value of the parameter.

getParameter

public String getParameter()

This method calls getMap().

Overrides:

getParameter in class IlvSDMRenderer

See Also:

IlvSDMRenderer.setParameter(java.lang.String)

getInstance

public static IlvMapRenderer getInstance(IlvSDMEngine engine)

Convenient function to get the IlvMapRenderer instance which belongs to the specified SDM engine.

Parameters:

engine - the SDM engine

Returns:

an instance of IlvMapRenderer, or null if no map renderer are used in the engine.

Since:

JViews 7.5

isUsingThreads

public boolean isUsingThreads()

Indicates whether the map read should use threads to load images and/or map data sources. In a thin client JSF application, for exemple, threads should be prevented. Default value depends on the presence of the "thin-client" pseudo class in the sdm engine. If the pseudo class is present it is false, else it is true.

Returns:

true if the map read should use threads, false if it should not.

Since:

JViews 8.0

See Also:

IlvMapInputStream.setGeneratingImage(Boolean)

setUsingThreads

public void setUsingThreads(boolean usingThreads)

Determines whether the map read should use threads to load images and/or map data sources.

Parameters:

usingThreads - true if threads should be authorized.

Since:

JViews 8.0

setEngine

public void setEngine(IlvSDMEngine engine)

Sets the IlvSDMEngine instance that has created this renderer. This method is called by the SDM engine, you should not call it directly.

Overrides:

setEngine in class IlvSDMRenderer

See Also:

IlvSDMRenderer.setEngine(ilog.views.sdm.IlvSDMEngine)

createNodeGraphic

public IlvGraphic createNodeGraphic(IlvSDMEngine engine,
                                    Object node)

This method simply calls the createNodeGraphic method of the filtered renderer. This method has been overridden to hide the graphic object if it has invalid coordinates.

Overrides:

createNodeGraphic in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine associated with the grapher in which the graphic object will be added.

node - The data node to translate into an IlvGraphic.

Since:

JViews 8.7

See Also:

createNodeGraphic(IlvSDMEngine, Object)

createLinkGraphic

public IlvGraphic createLinkGraphic(IlvSDMEngine engine,
                                    Object link,
                                    IlvGraphic from,
                                    IlvGraphic to)

This method simply calls the createLinkGraphic method of the filtered renderer. This method has been overridden to hide the link if one of its extremities has invalid coordinates.

Overrides:

createLinkGraphic in class IlvFilterSDMRenderer

Parameters:

engine - The SDM engine associated with the grapher in which the graphic object will be added.

link - The data link to translate into an IlvGraphic.

from - The graphic object associated with the source node of the link.

to - The graphic object associated with the destination node of the link.

Since:

JViews 8.7

See Also:

createNodeGraphic(IlvSDMEngine, Object)

isHideInvalidNodesAndLinks

public boolean isHideInvalidNodesAndLinks()

Indicates whether or not nodes that are not within the limits tolerated by the map projection will be hidden.

Returns:

true if nodes with invalid coordinates will be hidden.

Since:

JViews 8.7

setHideInvalidNodesAndLinks

public void setHideInvalidNodesAndLinks(boolean hideInvalidNodesAndLinks)

Indicates whether or not nodes that are not within the limits tolerated by the map projection will be hidden. When this flag is activated, and if the node latitude and longitude cannot be transformed in valid x/y coordinates, the node graphic and the links coming into and out of it will be made invisible. Note that changing this flag will not have any action by itself, but will take effect when the diagram is rendered again. In JView 8.7, the default value is true.

Parameters:

hideInvalidNodesAndLinks - true if invalid nodes will be hidden.

Since:

JViews 8.7