ESRIMap (SAS AppDevStudio API Developer Documentation for Java)

The ESRIMap class is, at it's core, an image server, whose images are retrieved from a running ArcGIS Server. It encapsulates all of the communication with the ArcGIS Server,and the interfaces and classes for managing and manipulating maps via that server. Map layer management, zooming, panning, selections, etc. are handled by the methods on this class. There are no OLAP specific implementations on this class, so it should be able to be used in relational data applications, as well.

After getting a map image, always disconnect from the ArcGIS Server. Thus, you should connect to the server, get an image, and disconnect. If you neglect the disconnect() after connecting and using a map, the map service will be held the ArcGIS Server, which has a limited number of instances available.

Using the ESRIMap class, you can perform basic operations such as zoom, pan, selection, etc.

Working with layers from the MapService: Each map service is comprised of layers. There must be a corresponding layer to the data that you send to ESRIMap. The linking between the data and the map layer is done with the descriptorList that is passed into the classify() method and with layername and fieldname.

Retrieving the MapImage: The map and legend image are returned as PNG encoded MIME data, in the form of a byte stream. The following code may be used to convert the byte stream into a Java Image.

 ImageIcon myImageIcon = new ImageIcon( esriMap.getImageMimeData() );
 Image myImage = myImageIcon.getImage();

Constructor Summary

ESRIMap()
          Initializes a newly created object

ESRIMap(ESRIConnection connection)
          Creates a new ESRIMap, and initializes a server based on the information in the provided ESRIConnection object.

Method Summary

void applyGraphStyle(GraphStyle style)
          This method sets color and font information on ESRIMap.

double calculateDistance(int startx, int starty, int endx, int endy)
          Returns the distance (in map coordinates) between two points (in screen coordinates)

java.lang.String chooseField(java.lang.Object[] data, java.lang.String layerName, java.lang.String[] fieldNames, int numToCheck)
          Selects a field, from those provided, that best matches the provided data.

void classify(com.sas.graphics.components.CategorizationModel cm, java.lang.String layerName, java.lang.String fieldName, java.lang.String[] descriptorList, java.lang.Double[] valueList, java.lang.Boolean[] exceptionList)
          Classifies the map based on the desired classification type and the number of desired breaks.

void clearAllSubsets()
          Clears any subsets that have been applied to the map.

void clearAnnotations()
          Clears any MapAnnotations that have been set on this object.

void clearSelections()
          Clears any selections that have been set on the map.

void clearSubset(java.lang.String layerName)
          Clears any subset that's been set on a specific layer.

void connect()
          Establish the connection to ArcGIS Server.

double[] convertToMapCoord(int x, int y)
          Converts a screen coordinate to a map coordinate

void disconnect()
          Release Context and remove all the connection between Client and ArcGIS Server.

java.util.HashMap getDefaultLayerVisibilities()
          Gets a list of the layers available on the map service, and a value indicating their default visibility.

java.lang.String[] getFieldNames(java.lang.String layerName)
          Returns an array of field names available on the specified layer of the map service.

java.lang.Object[] getFieldValues(java.lang.String layerName, java.lang.String fieldName, int numValues)
          Returns an array of values from the map service, based on the layerName and fieldName provided.

java.lang.String getImageDescription()
          Return the Image Description as String.

byte[] getImageMimeData()
          Returns the generated map image as MIME Data.

java.lang.String getImageURL()
          When using this method the map image is stored on the ArcGIS server, and a URL is passed back to use as a link to the image.

com.esri.arcgis.carto.IMap getIMap()
          Returns the IMap reference used by this object.

com.esri.arcgis.carto.IMapServer getIMapServer()
          Returns the IMapServer reference used by this object.

java.lang.String[] getLayerNames()
          Returns a list of all layer names on the map service.

java.util.HashMap getLayerVisibilities()
          Gets a list of the layers available on the map service, and a value indicating their visibility.

java.lang.String getLayerVisibility(java.lang.String layerName)
          Returns whether the specified layer is visible
Possible values are: ESRIConnection.ESRI_LAYER_ALWAYSOFF - The indicated layer is never drawn.

byte[] getLegendMimeData(boolean noDataToDisplay)
          Returns the legend image as MIME data.

java.lang.String getLegendTitle()
          Returns the currently set legend title.

java.lang.String getLegendValueFormat()
          Returns the format that is currently being used by the legend values.

java.util.Locale getLocale()
          Returns the Locale object used by this class.

void getMap()
          Loads the map with the default map and image descriptions.

void getMap(java.lang.String strMapDesc, java.lang.String strImageDesc)
          Loads the map based on the passed in mapDescription and imageDescription.

java.lang.String getMapDescription()
          Return the Description as String.

double[] getMapExtents()
          Returns the currently used map extents.

java.lang.String[] getMapServiceNames()
          Returns a list of ESRI Map Service names that are available on the map server.

java.lang.String[] getSelectList(java.util.Map layerToFieldMap)
          Returns a list of selected regions.

java.lang.String[] identify(int x, int y)
          Identifies a map feature based on Mouse click selection.

java.lang.String[] identify(int x, int y, java.lang.String[] fieldIds)
          Identifies a map feature based on Mouse click selection.

boolean isShowLegendTitle()
          Returns whether the legend title is currently displayed.

boolean isShowMissing()
          Returns whether missing values should show up in the legend, if they are present in the map.

boolean isUseBoundsColors()
          Sets whether the overflow and underflow colors should be used.

boolean isUseTwoColorRamp()
          Returns whether the ESRIMap is currently using a two color ramp.

boolean isValidLayer(java.lang.String layerName)
          Checks to see if layerName is a valid layer on the map service.

boolean isValidLayerAndField(java.lang.String layerName, java.lang.String fieldName)
          This is a convenience method that will check to see if the passed in layer name is valid, and if so, whether fieldName is a valid field on that layer.

void pan(int startx, int starty, int endx, int endy)
          Pans the current map extent.

int rectangularSelect(int startx, int starty, int endx, int endy, boolean controlPressed, java.lang.String classifiedLayer)
          Uses a rectangle to select regions and add their feature IDs to the selection list.

void resetMapDescription()
          Resets the saved map description to the current map description.

int select(int x, int y, boolean controlPressed, java.lang.String classifiedLayer)
          Selects a map region and adds its feature ID to the selection list

int selectByField(java.lang.String[] values, boolean controlPressed, java.lang.String classifiedLayer, java.lang.String fieldName)
          This method will search through the features on the passed in classifiedLayer, and select those features in which the fieldName is equal to one of the passed in values.

java.lang.String[] selectLayerAndField(int x, int y, java.util.Map layerToFieldMap)
          Utility routine to retrieve the map layer and field value based on mouse click location.

void setAnnotations(java.util.ArrayList annotations)
          Sets an ArrayList of MapAnnotations that are drawn on the map.

void setLayerVisibilities(java.util.HashMap map)
          Sets the visibilities of the layers using the passed-in HashMap.

void setLayerVisibility(java.lang.String layerName, java.lang.String visible)
          Changes the visibility of the passed-in layer.

void setLegendImageSize(java.awt.Dimension d)
          Sets the size of the exported legend image.

void setLegendTitle(java.lang.String legendTitle)
          Sets the title to be displayed on the legend image.

void setLegendValueFormat(java.lang.String legendFormat)
          Sets the format to be used on the legend values.

void setLocale(java.util.Locale locale)
          Sets the Locale object used by this class.

void setMapExtents(double xmin, double xmax, double ymin, double ymax)
          Sets the map extents that should be used for this map.

void setMapImageSize(java.awt.Dimension d)
          Sets the size of the exported map image.

void setShowLegendTitle(boolean showLegendTitle)
          Sets whether or not the legend title should be displayed in the legend image.

void setShowMissing(boolean showMissing)
          Sets whether missing values should show up in the legend, if they are present in the map.

void setUseBoundsColors(boolean useBoundsColors)
          Returns whether the overflow and underflow colors should be used for values that don't fall into a range.

void setUseTwoColorRamp(boolean useTwoColorRamp)
          ESRIMap can either use a two color ramp or a three color ramp when creating colors for classifying the data.

void subset(java.lang.String layerName, java.lang.String fieldName, java.lang.String[] values)
          Subsets the map based on the features described by the fieldName and values parameters.

double[] testData(java.lang.Object[] data, java.lang.String layerName, java.lang.String fieldName)
          This method checks to see how much of the passed-in data matches the data that is found on the ESRI map service.

void undoClassification(java.lang.String layerName)
          Undoes any classification that has been done on the specified layer.

double[] zoomFeatures(java.lang.String layerName, java.lang.String fieldName, java.lang.String[] values)
          Zooms to the minimum extents that surround the features described by the fieldName and values parameters.

void zoomFullExtent()
          Zooms the extent of the current map to the full extent of that map, which is the default extent on that map service.

void zoomIn(int x, int y, double factor)
          Zooms and centers the extent of the current map to the specified pixelX, pixelY, and factor arguments.

void zoomOut(int x, int y, double factor)
          Zooms out and centers the extent of the current to the specified pixelX, pixelY, and factor arguments.

void zoomTo(int startx, int starty, int endx, int endy)
          Zooms the map to the provided rectangle, defined in pixel coordinates pixelX, pixelY, and factor arguments.

void zoomTo(long startx, long starty, long endx, long endy)
          Zooms the map to the provided rectangle, defined in map coordinates.

Constructor Summary
`ESRIMap()` Initializes a newly created object
`ESRIMap(ESRIConnection connection)` Creates a new ESRIMap, and initializes a server based on the information in the provided ESRIConnection object.

Method Summary
`void`	`applyGraphStyle(GraphStyle style)` This method sets color and font information on ESRIMap.
`double`	`calculateDistance(int startx, int starty, int endx, int endy)` Returns the distance (in map coordinates) between two points (in screen coordinates)
`java.lang.String`	`chooseField(java.lang.Object[] data, java.lang.String layerName, java.lang.String[] fieldNames, int numToCheck)` Selects a field, from those provided, that best matches the provided data.
`void`	`classify(com.sas.graphics.components.CategorizationModel cm, java.lang.String layerName, java.lang.String fieldName, java.lang.String[] descriptorList, java.lang.Double[] valueList, java.lang.Boolean[] exceptionList)` Classifies the map based on the desired classification type and the number of desired breaks.
`void`	`clearAllSubsets()` Clears any subsets that have been applied to the map.
`void`	`clearAnnotations()` Clears any MapAnnotations that have been set on this object.
`void`	`clearSelections()` Clears any selections that have been set on the map.
`void`	`clearSubset(java.lang.String layerName)` Clears any subset that's been set on a specific layer.
`void`	`connect()` Establish the connection to ArcGIS Server.
`double[]`	`convertToMapCoord(int x, int y)` Converts a screen coordinate to a map coordinate
`void`	`disconnect()` Release Context and remove all the connection between Client and ArcGIS Server.
`java.util.HashMap`	`getDefaultLayerVisibilities()` Gets a list of the layers available on the map service, and a value indicating their default visibility.
`java.lang.String[]`	`getFieldNames(java.lang.String layerName)` Returns an array of field names available on the specified layer of the map service.
`java.lang.Object[]`	`getFieldValues(java.lang.String layerName, java.lang.String fieldName, int numValues)` Returns an array of values from the map service, based on the layerName and fieldName provided.
`java.lang.String`	`getImageDescription()` Return the Image Description as String.
`byte[]`	`getImageMimeData()` Returns the generated map image as MIME Data.
`java.lang.String`	`getImageURL()` When using this method the map image is stored on the ArcGIS server, and a URL is passed back to use as a link to the image.
`com.esri.arcgis.carto.IMap`	`getIMap()` Returns the IMap reference used by this object.
`com.esri.arcgis.carto.IMapServer`	`getIMapServer()` Returns the IMapServer reference used by this object.
`java.lang.String[]`	`getLayerNames()` Returns a list of all layer names on the map service.
`java.util.HashMap`	`getLayerVisibilities()` Gets a list of the layers available on the map service, and a value indicating their visibility.
`java.lang.String`	`getLayerVisibility(java.lang.String layerName)` Returns whether the specified layer is visible Possible values are: ESRIConnection.ESRI_LAYER_ALWAYSOFF - The indicated layer is never drawn.
`byte[]`	`getLegendMimeData(boolean noDataToDisplay)` Returns the legend image as MIME data.
`java.lang.String`	`getLegendTitle()` Returns the currently set legend title.
`java.lang.String`	`getLegendValueFormat()` Returns the format that is currently being used by the legend values.
`java.util.Locale`	`getLocale()` Returns the Locale object used by this class.
`void`	`getMap()` Loads the map with the default map and image descriptions.
`void`	`getMap(java.lang.String strMapDesc, java.lang.String strImageDesc)` Loads the map based on the passed in mapDescription and imageDescription.
`java.lang.String`	`getMapDescription()` Return the Description as String.
`double[]`	`getMapExtents()` Returns the currently used map extents.
`java.lang.String[]`	`getMapServiceNames()` Returns a list of ESRI Map Service names that are available on the map server.
`java.lang.String[]`	`getSelectList(java.util.Map layerToFieldMap)` Returns a list of selected regions.
`java.lang.String[]`	`identify(int x, int y)` Identifies a map feature based on Mouse click selection.
`java.lang.String[]`	`identify(int x, int y, java.lang.String[] fieldIds)` Identifies a map feature based on Mouse click selection.
`boolean`	`isShowLegendTitle()` Returns whether the legend title is currently displayed.
`boolean`	`isShowMissing()` Returns whether missing values should show up in the legend, if they are present in the map.
`boolean`	`isUseBoundsColors()` Sets whether the overflow and underflow colors should be used.
`boolean`	`isUseTwoColorRamp()` Returns whether the ESRIMap is currently using a two color ramp.
`boolean`	`isValidLayer(java.lang.String layerName)` Checks to see if layerName is a valid layer on the map service.
`boolean`	`isValidLayerAndField(java.lang.String layerName, java.lang.String fieldName)` This is a convenience method that will check to see if the passed in layer name is valid, and if so, whether fieldName is a valid field on that layer.
`void`	`pan(int startx, int starty, int endx, int endy)` Pans the current map extent.
`int`	`rectangularSelect(int startx, int starty, int endx, int endy, boolean controlPressed, java.lang.String classifiedLayer)` Uses a rectangle to select regions and add their feature IDs to the selection list.
`void`	`resetMapDescription()` Resets the saved map description to the current map description.
`int`	`select(int x, int y, boolean controlPressed, java.lang.String classifiedLayer)` Selects a map region and adds its feature ID to the selection list
`int`	`selectByField(java.lang.String[] values, boolean controlPressed, java.lang.String classifiedLayer, java.lang.String fieldName)` This method will search through the features on the passed in classifiedLayer, and select those features in which the fieldName is equal to one of the passed in values.
`java.lang.String[]`	`selectLayerAndField(int x, int y, java.util.Map layerToFieldMap)` Utility routine to retrieve the map layer and field value based on mouse click location.
`void`	`setAnnotations(java.util.ArrayList annotations)` Sets an ArrayList of MapAnnotations that are drawn on the map.
`void`	`setLayerVisibilities(java.util.HashMap map)` Sets the visibilities of the layers using the passed-in HashMap.
`void`	`setLayerVisibility(java.lang.String layerName, java.lang.String visible)` Changes the visibility of the passed-in layer.
`void`	`setLegendImageSize(java.awt.Dimension d)` Sets the size of the exported legend image.
`void`	`setLegendTitle(java.lang.String legendTitle)` Sets the title to be displayed on the legend image.
`void`	`setLegendValueFormat(java.lang.String legendFormat)` Sets the format to be used on the legend values.
`void`	`setLocale(java.util.Locale locale)` Sets the Locale object used by this class.
`void`	`setMapExtents(double xmin, double xmax, double ymin, double ymax)` Sets the map extents that should be used for this map.
`void`	`setMapImageSize(java.awt.Dimension d)` Sets the size of the exported map image.
`void`	`setShowLegendTitle(boolean showLegendTitle)` Sets whether or not the legend title should be displayed in the legend image.
`void`	`setShowMissing(boolean showMissing)` Sets whether missing values should show up in the legend, if they are present in the map.
`void`	`setUseBoundsColors(boolean useBoundsColors)` Returns whether the overflow and underflow colors should be used for values that don't fall into a range.
`void`	`setUseTwoColorRamp(boolean useTwoColorRamp)` ESRIMap can either use a two color ramp or a three color ramp when creating colors for classifying the data.
`void`	`subset(java.lang.String layerName, java.lang.String fieldName, java.lang.String[] values)` Subsets the map based on the features described by the fieldName and values parameters.
`double[]`	`testData(java.lang.Object[] data, java.lang.String layerName, java.lang.String fieldName)` This method checks to see how much of the passed-in data matches the data that is found on the ESRI map service.
`void`	`undoClassification(java.lang.String layerName)` Undoes any classification that has been done on the specified layer.
`double[]`	`zoomFeatures(java.lang.String layerName, java.lang.String fieldName, java.lang.String[] values)` Zooms to the minimum extents that surround the features described by the fieldName and values parameters.
`void`	`zoomFullExtent()` Zooms the extent of the current map to the full extent of that map, which is the default extent on that map service.
`void`	`zoomIn(int x, int y, double factor)` Zooms and centers the extent of the current map to the specified pixelX, pixelY, and factor arguments.
`void`	`zoomOut(int x, int y, double factor)` Zooms out and centers the extent of the current to the specified pixelX, pixelY, and factor arguments.
`void`	`zoomTo(int startx, int starty, int endx, int endy)` Zooms the map to the provided rectangle, defined in pixel coordinates pixelX, pixelY, and factor arguments.
`void`	`zoomTo(long startx, long starty, long endx, long endy)` Zooms the map to the provided rectangle, defined in map coordinates.

Constructor Detail

ESRIMap

public ESRIMap()

Initializes a newly created object

ESRIMap

public ESRIMap(ESRIConnection connection)

Creates a new ESRIMap, and initializes a server based on the information in the provided ESRIConnection object.

Parameters:: connection - - Contains the information needed to connect and use the ESRI server
See Also:: ESRIConnection

Method Detail

connect

public void connect()
             throws ESRIException

Establish the connection to ArcGIS Server. This method will throw an exception when the server connection cannot be established. A server context is created, which must be released using the #disconnect method. This method must be called before the ESRIMap is used.

NOTE!!! It is very important that the call to disconnect() is made after the map has been used. Failure to do so will cause the map service to be held by the ArcGIS Server, which has a limited number of instances available. The intended use is to connect to the service, get an image, and disconnect.

Throws:: ESRIException - when Server does not exist or wrong authetication details
See Also:: disconnect()

disconnect

public void disconnect()
                throws ESRIException

Release Context and remove all the connection between Client and ArcGIS Server.

Throws:: ESRIException - when server fails to release object
See Also:: connect()

getMapDescription

public java.lang.String getMapDescription()

Return the Description as String. The string returned from this message can be used to save the map's state, and thus recreate it in the same state at a later time. For instance, it can be saved to the session, and pulled back out after a subsequent operation.

Returns:: the current Description

getImageDescription

public java.lang.String getImageDescription()

Return the Image Description as String. The string returned from this message can be used to save the map image's state, and thus recreate it in the same state at a later time. For instance, it can be saved to the session, and pulled back out after a subsequent operation.

Returns:: the current Image Description

getMap

public void getMap(java.lang.String strMapDesc,
                   java.lang.String strImageDesc)
            throws ESRIException

Loads the map based on the passed in mapDescription and imageDescription.

Parameters:: strMapDesc - value of Map Description; strImageDesc - value of Image Description
Throws:: ESRIException - when either Map or Image Description are not able to load
See Also:: resetMapDescription(), getMapDescription(), getImageDescription()

getMap

public void getMap()
            throws ESRIException

Loads the map with the default map and image descriptions.

Throws:: ESRIException - when there is a problem connecting or getting information from the ESRI server.

getImageURL

public java.lang.String getImageURL()
                             throws ESRIException

When using this method the map image is stored on the ArcGIS server, and a URL is passed back to use as a link to the image.

Returns:: generated url from ArcGIS server
Throws:: ESRIException - failed to get the url from ArcGIS Server
See Also:: getImageMimeData()

getImageMimeData

public byte[] getImageMimeData()
                        throws ESRIException

Returns the generated map image as MIME Data.

Returns:: mapimage as byte[]
Throws:: ESRIException - failed to get the MimeData from ArcGIS Server
See Also:: getImageURL()

getLegendMimeData

public byte[] getLegendMimeData(boolean noDataToDisplay)

Returns the legend image as MIME data. Since the legend is drawn using an internal subsystem, it cannot be returned as a URL.

Parameters:: noDataToDisplay - true if there is no data to draw a legend with, or if the user wantes the default, "No values" legend.
Returns:: byte stream that encodes the legend image as MIME data
See Also:: getImageMimeData()

zoomIn

public void zoomIn(int x,
                   int y,
                   double factor)
            throws ESRIException

Zooms and centers the extent of the current map to the specified pixelX, pixelY, and factor arguments.

Parameters:: x - the X pixel value to center.; y - the Y pixel value to center.; factor - the value to zoom the map by.
Throws:: ESRIException - when there is a problem connecting or getting information from the ESRI server.

resetMapDescription

public void resetMapDescription()

Resets the saved map description to the current map description.

zoomTo

public void zoomTo(int startx,
                   int starty,
                   int endx,
                   int endy)
            throws ESRIException

Zooms the map to the provided rectangle, defined in pixel coordinates pixelX, pixelY, and factor arguments.

Parameters:: startx - the X pixel value of the top left corner.; starty - the Y pixel value of the top left corner.; endx - the X pixel value of the bottom right corner.; endy - the Y pixel value of the bottom right corner.
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

zoomTo

public void zoomTo(long startx,
                   long starty,
                   long endx,
                   long endy)
            throws ESRIException

Zooms the map to the provided rectangle, defined in map coordinates.

Parameters:: startx - the X value of the top left corner.; starty - the Y value of the top left corner.; endx - the X value of the bottom right corner.; endy - the Y value of the bottom right corner.
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

zoomFeatures

public double[] zoomFeatures(java.lang.String layerName,
                             java.lang.String fieldName,
                             java.lang.String[] values)
                      throws ESRIException

Zooms to the minimum extents that surround the features described by the fieldName and values parameters. For instance, this can be used to zoom into North Carolina and South Carolina by passing in values of:

layerName = "States"

fieldName = "StateName"

vales = ["North Carolina","South Carolina"]

Parameters:: layerName - - The name of the layer to search; fieldName - - The field in the map service to use; values - - The values for the field to "subset", find the extents, and return them.
Returns:: a double array of the resulting envelope, defined as [xmin,xmax,ymin,ymax]
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

subset

public void subset(java.lang.String layerName,
                   java.lang.String fieldName,
                   java.lang.String[] values)
            throws ESRIException

Subsets the map based on the features described by the fieldName and values parameters. For instance, this method can be used to only show North Carolina and South Carolina by passing in values of:

layerName = "States"

fieldName = "StateName"

vales = ["North Carolina","South Carolina"]

Note: In order to see the effects of this method, the layer must be visible.

Parameters:: layerName - - The name of the layer to search; fieldName - - The field in the map service to use; values - - The values for the field to subset
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.
See Also:: setLayerVisibilities(HashMap), setLayerVisibility(String, String)

clearAllSubsets

public void clearAllSubsets()
                     throws ESRIException

Clears any subsets that have been applied to the map.

Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

clearSubset

public void clearSubset(java.lang.String layerName)
                 throws ESRIException

Clears any subset that's been set on a specific layer.

Parameters:: layerName - - The layer name
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

identify

public java.lang.String[] identify(int x,
                                   int y)
                            throws ESRIException

Identifies a map feature based on Mouse click selection. This method returns an array of Strings, where every two strings represents a name value pair in the ESRI map service. For instance, if there were two fields returned for state name and FIPS code, the array might contain:

["StateName","North Carolina","FIPS","37"]

Parameters:: x - the X pixel value of selection.; y - the Y pixel value of selection.
Returns:: array of name/value pairs
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

identify

public java.lang.String[] identify(int x,
                                   int y,
                                   java.lang.String[] fieldIds)
                            throws ESRIException

["StateName","North Carolina","FIPS","37"]

Parameters:: x - the X pixel value of selection.; y - the Y pixel value of selection.; fieldIds - the field name of the desired field/value pairs to return. If this is null, all field/value pairs are returned.
Returns:: array of name/value pairs
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

zoomOut

public void zoomOut(int x,
                    int y,
                    double factor)
             throws ESRIException

Zooms out and centers the extent of the current to the specified pixelX, pixelY, and factor arguments.

Parameters:: x - the X pixel value to center.; y - the Y pixel value to center.; factor - - How much to zoom out.
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

zoomFullExtent

public void zoomFullExtent()
                    throws ESRIException

Zooms the extent of the current map to the full extent of that map, which is the default extent on that map service.

Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

pan

public void pan(int startx,
                int starty,
                int endx,
                int endy)
         throws ESRIException

Pans the current map extent. The amount that the extent is moved is defined by endx-startx, endy-starty, which is then mapped into map coordinates.

Parameters:: startx -; starty -; endx -; endy -
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

getLayerNames

public java.lang.String[] getLayerNames()
                                 throws ESRIException

Returns a list of all layer names on the map service.

Returns:: List of layer names
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

setLayerVisibilities

public void setLayerVisibilities(java.util.HashMap map)
                          throws ESRIException

Sets the visibilities of the layers using the passed-in HashMap. The map must contain a series of entries where each entry has a key of the layer name, and a value of one of the following:

ESRIConnection.ESRI_LAYER_ALWAYSON - The indicated layer is always drawn. This is not currently supported.
ESRIConnection.ESRI_LAYER_ALWAYSOFF - The indicated layer is never drawn.
ESRIConnection.ESRI_LAYER_USEMAPSERVICERULES - The layer is drawn according to map service rules. Thus, at the appropriate height (or zoom level), the layer will appear. This is setup beforehand by the builder of the map service.

Parameters:: map - a HashMap containing entries with a layername as a key and one of the above visibility values as its value
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.
See Also:: setLayerVisibility(String, String)

setLayerVisibility

public void setLayerVisibility(java.lang.String layerName,
                               java.lang.String visible)
                        throws ESRIException

Changes the visibility of the passed-in layer. Currently only ESRIConnection.ESRI_LAYER_USEMAPSERVICERULES and ESRIConnection.ESRI_LAYER_ALWAYS_ON are supported. Thus, it is not currently possible to always turn a layer on, and override the map service rules set by the ESRI map administrator.

Parameters:: layerName - - The name of the layer; visible - - The new visibility value
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

clearSelections

public void clearSelections()
                     throws ESRIException

Clears any selections that have been set on the map.

Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

classify

public void classify(com.sas.graphics.components.CategorizationModel cm,
                     java.lang.String layerName,
                     java.lang.String fieldName,
                     java.lang.String[] descriptorList,
                     java.lang.Double[] valueList,
                     java.lang.Boolean[] exceptionList)
              throws ESRIException

Classifies the map based on the desired classification type and the number of desired breaks. Thus, each region of the map is assigned one of n colors, with n being the number of breaks.

The supported classification types are:

GraphConstants.CATEGORIZATION_EQUAL_INTERVAL - This algorithm breaks the data up into equally spaced intervals.
GraphConstants.CATEGORIZATION_EQUAL_DISTRIBUTION - This algorithm attempts to create the intervals in such a way that each bucket contains approximately the same number of values.
GraphConstants.CATEGORIZATION_NATURAL_BREAKS - This algorithm attempts to find the "natural" breaks in the data and creates the intervals around them.
GraphConstants.CATEGORIZATION_STANDARD_DEVIATION - This algorithm uses the standard deviation of the measure values to create the intervals. Each interval represents some distance from the mean.

Parameters:

cm - - The CategorizationModel used to determine the break values.

layerName - - The layer name to classify.

fieldName - - The field on that layer to use

descriptorList - - A list of the id field values of the map features to classify. For instance, the array might be { "NC","SC" } if North Carolina and South Carolina were to be classified.

valueList - - A list of values that correspond to the descriptorList. This array represents the measure value for each colored feature. For instance, using the above example, the array might be { 100000, 112000 } if North Carolina had a measure value of 100000 and South Carolina had a measure value of 112000.

exceptionList - - A list of booleans that determine if each observation should be represented by the excepetion color, instead of drawn in the normal color. This list can be null.

Note: In order for the effects of this method to be seen, the layer must be visible.

Throws:

ESRIException - when there is a problem connecting to or getting information from the ESRI server.

undoClassification

public void undoClassification(java.lang.String layerName)
                        throws ESRIException

Undoes any classification that has been done on the specified layer.

Parameters:: layerName - The name of the layer
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.
See Also:: classify(CategorizationModel, String, String, String[], Double[], Boolean[])

setMapExtents

public void setMapExtents(double xmin,
                          double xmax,
                          double ymin,
                          double ymax)
                   throws ESRIException

Sets the map extents that should be used for this map. The coordinates are assumed to be in the same system as the map.

Parameters:: xmin - - Minimum x value of the envelope to use; xmax - - Maximum x value of the envelope to use; ymin - - Minimum y value of the envelope to use; ymax - - Maximum y value of the envelope to use
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

getMapExtents

public double[] getMapExtents()
                       throws ESRIException

Returns the currently used map extents. The array is defined to be { xmin, xmax, ymin, ymax }.

Returns:: - The currently used map extents
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server. Most likely this is due to not finding a map area or its extents.

getSelectList

public java.lang.String[] getSelectList(java.util.Map layerToFieldMap)
                                 throws ESRIException

Returns a list of selected regions. Each value in the returned String array will be the value of the field used for the layer in which the selected region appears.

Parameters:: layerToFieldMap - The Map of layer names and corresponding field names
Returns:: List of the selected regions
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

selectLayerAndField

public java.lang.String[] selectLayerAndField(int x,
                                              int y,
                                              java.util.Map layerToFieldMap)
                                       throws ESRIException

Utility routine to retrieve the map layer and field value based on mouse click location.

Parameters:: x - the X pixel value of mouse click event.; y - the Y pixel value of mouse click event.; layerToFieldMap - the map of which fields to use with which layers.
Returns:: an array of String, of length 2, where the first value represents the layer of the selected feature, and the second represents the value of the field indicated by the layerToField map.
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

rectangularSelect

public int rectangularSelect(int startx,
                             int starty,
                             int endx,
                             int endy,
                             boolean controlPressed,
                             java.lang.String classifiedLayer)
                      throws ESRIException

Uses a rectangle to select regions and add their feature IDs to the selection list.

Parameters:: startx - The x value of the top-left corner of the selection rectangle, in pixel coordinates; starty - The y value of the top-left corner of the selection rectangle, in pixel coordinates; endx - The x value of the bottom-right corner of the selection rectangle, in pixel coordinates; endy - The y value of the bottom-right corner of the selection rectangle, in pixel coordinates; controlPressed - If control is pressed, any resulting selections will be added to the current selection list. Otherwise, they will replace the current list.; classifiedLayer - The layer that is currently being classified.
Returns:: How many were selected
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

select

public int select(int x,
                  int y,
                  boolean controlPressed,
                  java.lang.String classifiedLayer)
           throws ESRIException

Selects a map region and adds its feature ID to the selection list

Parameters:: x - The X pixel value of selection point.; y - The Y pixel value of selection point.; controlPressed - - If control is pressed, any resulting selections will be added to the current selection list. Otherwise, they will replace the current list.; classifiedLayer - - The layer that is currently being classified.
Returns:: How many were selected
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

calculateDistance

public double calculateDistance(int startx,
                                int starty,
                                int endx,
                                int endy)
                         throws ESRIException

Returns the distance (in map coordinates) between two points (in screen coordinates)

Parameters:: startx - The start x position; starty - The start y position; endx - The end x position; endy - The end y position
Returns:: The distance (in map coordinates)
Throws:: ESRIException

selectByField

public int selectByField(java.lang.String[] values,
                         boolean controlPressed,
                         java.lang.String classifiedLayer,
                         java.lang.String fieldName)
                  throws ESRIException

This method will search through the features on the passed in classifiedLayer, and select those features in which the fieldName is equal to one of the passed in values.

Parameters:: values - the values to select; controlPressed - whether to keep any previous selections; classifiedLayer - the name of the layer to select on; fieldName - the name of the field on that layer
Returns:: the number of values selected
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

setMapImageSize

public void setMapImageSize(java.awt.Dimension d)

Sets the size of the exported map image.

Parameters:: d - The size of the image

setLegendImageSize

public void setLegendImageSize(java.awt.Dimension d)

Sets the size of the exported legend image.

Parameters:: d - The size of the image

getLocale

public java.util.Locale getLocale()

Returns the Locale object used by this class.

Returns:: Returns the locale.

setLocale

public void setLocale(java.util.Locale locale)

Sets the Locale object used by this class.

Parameters:: locale - The locale to set.

isShowMissing

public boolean isShowMissing()

Returns whether missing values should show up in the legend, if they are present in the map. By default missing values are not displayed as an entry in the legend.

Returns:: Whether missings are shown in the legend

setShowMissing

public void setShowMissing(boolean showMissing)

Sets whether missing values should show up in the legend, if they are present in the map. By default missing values are not displayed as an entry in the legend.

Parameters:: showMissing - Boolean used to display missings in the legend.

isUseTwoColorRamp

public boolean isUseTwoColorRamp()

Returns whether the ESRIMap is currently using a two color ramp.

Returns:: Returns the useTwoColorRamp.
See Also:: setUseTwoColorRamp(boolean)

setUseTwoColorRamp

public void setUseTwoColorRamp(boolean useTwoColorRamp)

ESRIMap can either use a two color ramp or a three color ramp when creating colors for classifying the data. The colors are defined using startColor, midColor, and endColor. If useTwoColorRamp is true, the midColor is ignored when calculating the colors to use in the ramp. If false, the midColor is used so that approximately the first half of the colors range from the start color to the mid color, and the second half of the colors range from the mid color to the end color.

Parameters:: useTwoColorRamp - The useTwoColorRamp to set.
See Also:: setStartColor(Color), setMidColor(Color), setEndColor(Color)

getLegendValueFormat

public java.lang.String getLegendValueFormat()

Returns the format that is currently being used by the legend values. The default value is "BEST12".

Returns:: The currently set format.
See Also:: setLegendValueFormat(String)

setLegendValueFormat

public void setLegendValueFormat(java.lang.String legendFormat)

Sets the format to be used on the legend values.

Parameters:: legendFormat - The legendFormat to set.
See Also:: getLegendValueFormat()

getLayerVisibilities

public java.util.HashMap getLayerVisibilities()
                                       throws ESRIException

Gets a list of the layers available on the map service, and a value indicating their visibility.
Possible values in the map are:

ESRIConnection.ESRI_LAYER_ALWAYSOFF - The indicated layer is never drawn.
ESRIConnection.ESRI_LAYER_USEMAPSERVICERULES - The layer is drawn according to map service rules. Thus, at the appropriate height (or zoom level), the layer will appear. This is setup beforehand by the builder of the map service.

Returns:: HashMap of the visibilites of each layer
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.
See Also:: setLayerVisibilities(HashMap), setLayerVisibility(String, String)

getDefaultLayerVisibilities

public java.util.HashMap getDefaultLayerVisibilities()
                                              throws ESRIException

Gets a list of the layers available on the map service, and a value indicating their default visibility.
Possible values in the map are:

ESRIConnection.ESRI_LAYER_ALWAYSOFF - The indicated layer is never drawn.
ESRIConnection.ESRI_LAYER_USEMAPSERVICERULES - The layer is drawn according to map service rules. Thus, at the appropriate height (or zoom level), the layer will appear. This is setup beforehand by the builder of the map service.

Returns:: HashMap of the visibilites of each layer
Throws:: ESRIException
See Also:: setLayerVisibilities(HashMap), setLayerVisibility(String, String)

getLayerVisibility

public java.lang.String getLayerVisibility(java.lang.String layerName)
                                    throws ESRIException

Returns whether the specified layer is visible
Possible values are:

ESRIConnection.ESRI_LAYER_ALWAYSOFF - The indicated layer is never drawn.
ESRIConnection.ESRI_LAYER_USEMAPSERVICERULES - The layer is drawn according to map service rules. Thus, at the appropriate height (or zoom level), the layer will appear. This is setup beforehand by the builder of the map service.

Parameters:: layerName - The name of the layer
Returns:: the current visibility of the passed in layer
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.
See Also:: setLayerVisibilities(HashMap), setLayerVisibility(String, String)

isValidLayer

public boolean isValidLayer(java.lang.String layerName)
                     throws ESRIException

Checks to see if layerName is a valid layer on the map service.

Parameters:: layerName - The name to check
Returns:: Whether it's a valid name
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

isValidLayerAndField

public boolean isValidLayerAndField(java.lang.String layerName,
                                    java.lang.String fieldName)
                             throws ESRIException

This is a convenience method that will check to see if the passed in layer name is valid, and if so, whether fieldName is a valid field on that layer.

Parameters:: layerName - The layer to check for; fieldName - The field on that layer
Returns:: Whether the layerName and fieldName are valid
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

getLegendTitle

public java.lang.String getLegendTitle()

Returns the currently set legend title. By default it's an empty String.

Returns:: The current legend title.

setLegendTitle

public void setLegendTitle(java.lang.String legendTitle)

Sets the title to be displayed on the legend image. By default the title is an empty string. The legend title is only displayed if showLegendTitle is set to true.

Parameters:: legendTitle - The new title
See Also:: getLegendTitle(), setShowLegendTitle(boolean)

isShowLegendTitle

public boolean isShowLegendTitle()

Returns whether the legend title is currently displayed.

Returns:: showLegendTitle
See Also:: setShowLegendTitle(boolean), setLegendTitle(String)

setShowLegendTitle

public void setShowLegendTitle(boolean showLegendTitle)

Sets whether or not the legend title should be displayed in the legend image. By default the legend is not displayed. The default value for the legend title is an empty String.

Parameters:: showLegendTitle - whether to show the legend title
See Also:: setLegendTitle(String), isShowLegendTitle()

getIMap

public com.esri.arcgis.carto.IMap getIMap()

Returns the IMap reference used by this object. This is not intended for normal consumption or use, but might be needed for those extending the functionality of ESRIMap.

Returns:: The IMap

getIMapServer

public com.esri.arcgis.carto.IMapServer getIMapServer()

Returns the IMapServer reference used by this object. This is not intended for normal consumption or use, but might be needed for those extending the functionality of ESRIMap.

Returns:: The IMapServer

getFieldValues

public java.lang.Object[] getFieldValues(java.lang.String layerName,
                                         java.lang.String fieldName,
                                         int numValues)
                                  throws ESRIException

Returns an array of values from the map service, based on the layerName and fieldName provided. The first n observations are returned, with n=numValues. If numValues is -1 then all values are returned.

Parameters:: layerName - Name of the ESRI map layer; fieldName - FieldName of the variable to look at; numValues - Number of values to return, or -1 to return all values
Returns:: an array of values fromthe map service.
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

testData

public double[] testData(java.lang.Object[] data,
                         java.lang.String layerName,
                         java.lang.String fieldName)
                  throws ESRIException

This method checks to see how much of the passed-in data matches the data that is found on the ESRI map service.

Parameters:: data - The data to check against; layerName - The layer on the ESRI map service; fieldName - The field name on that layer
Returns:: An array of two doubles. The first is the percentage of the passed-in data that matches what is found on the map service, essentially the coverage. The second double is the percentage of map data that matches the passed-in data. In both cases the percentage returned is the percentage of unique values that are found, not the percentage of total values. This method returns null if any of the inputs are null.
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

getFieldNames

public java.lang.String[] getFieldNames(java.lang.String layerName)
                                 throws ESRIException

Returns an array of field names available on the specified layer of the map service.

Parameters:: layerName - The layer to check
Returns:: An array of field names
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

chooseField

public java.lang.String chooseField(java.lang.Object[] data,
                                    java.lang.String layerName,
                                    java.lang.String[] fieldNames,
                                    int numToCheck)
                             throws ESRIException

Selects a field, from those provided, that best matches the provided data.

Parameters:: data - The array of data to check against; layerName - The layer of the map service to check; numToCheck - Number of map service values that should be used to check, or -1 to check all values
Returns:: A String representing the field name, or an empty String if none are valid or there are no matches
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

getMapServiceNames

public java.lang.String[] getMapServiceNames()
                                      throws ESRIException

Returns a list of ESRI Map Service names that are available on the map server. Each Map Service is guaranteed to be of type "MapServer".

Returns:: List of Map Service names
Throws:: ESRIException - when there is a problem connecting to or getting information from the ESRI server.

applyGraphStyle

public void applyGraphStyle(GraphStyle style)

This method sets color and font information on ESRIMap. The colors used by this object are the three ContinuousFillThreeColor colors, and the outline color. The other colors are hard-coded to match other components and settings, but that may change with later releases.

The font information for the legend values is also retrieved from the GraphStyle.

Parameters:: style - GraphStyle to use

isUseBoundsColors

public boolean isUseBoundsColors()

Sets whether the overflow and underflow colors should be used. If false, the default color is used for map area values that don't fall into a range.

Returns:: The boolean
See Also:: setUseBoundsColors(boolean)

setUseBoundsColors

public void setUseBoundsColors(boolean useBoundsColors)

Returns whether the overflow and underflow colors should be used for values that don't fall into a range. If this value is false then the default color is used instead. This value is only used when a specific categorization range is set on the object.

Parameters:: useBoundsColors - Whether to use the boundary colors.
See Also:: isUseBoundsColors()

setAnnotations

public void setAnnotations(java.util.ArrayList annotations)

Sets an ArrayList of MapAnnotations that are drawn on the map. Each element in the passed in collection is assumed to be of type MapAnnotation.

Parameters:: annotations -

clearAnnotations

public void clearAnnotations()

Clears any MapAnnotations that have been set on this object.

convertToMapCoord

public double[] convertToMapCoord(int x,
                                  int y)

Converts a screen coordinate to a map coordinate

Parameters:: x - The x position; y - The y position
Returns:: A double array, [x,y] of the calculated map coordinate

All Libraries

This Library

Package

Class

Use

Tree

Deprecated

Index

Grand Index

Help

Components

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.sas.graphics.map Class ESRIMap

ESRIMap

ESRIMap

connect

disconnect

getMapDescription

getImageDescription

getMap

getMap

getImageURL

getImageMimeData

getLegendMimeData

zoomIn

resetMapDescription

zoomTo

zoomTo

zoomFeatures

subset

clearAllSubsets

clearSubset

identify

identify

zoomOut

zoomFullExtent

pan

getLayerNames

setLayerVisibilities

setLayerVisibility

clearSelections

classify

undoClassification

setMapExtents

getMapExtents

getSelectList

selectLayerAndField

rectangularSelect

select

calculateDistance

selectByField

setMapImageSize

setLegendImageSize

getLocale

setLocale

isShowMissing

setShowMissing

isUseTwoColorRamp

setUseTwoColorRamp

getLegendValueFormat

setLegendValueFormat

getLayerVisibilities

getDefaultLayerVisibilities

getLayerVisibility

isValidLayer

isValidLayerAndField

getLegendTitle

setLegendTitle

isShowLegendTitle

setShowLegendTitle

getIMap

getIMapServer

getFieldValues

testData

getFieldNames

chooseField

getMapServiceNames

applyGraphStyle

isUseBoundsColors

setUseBoundsColors

setAnnotations

clearAnnotations

convertToMapCoord

com.sas.graphics.map
Class ESRIMap