Esri Business Analyst Online API for Flex - What's New in 2.0

The Business Analyst Online API for Flex 2.0 is a major release built on top of Adobe Flash 4.1 and ArcGIS API for Flex 2.1 or greater. The major updates relate to the full redesign of the thematic mapping functionality.

Note: The current implementation of the Core Thematic Mapping is preliminary. It is subject to change in the next release when new enhancements for the Thematic Mapping will be added.

Changes in Thematic Mapping

Many thematic mapping classes have been moved from com.esri.bao.tasks.thematicmapping to the new core com.esri.bacore.thematicmapping package.

  Color ramps

• The BAColorRamp class has been moved from com.esri.bao.tasks.thematicmapping to com.esri.bacore.thematicmapping and renamed TMColorRamp.
• The ColorRamp class has been moved from com.esri.bao.tasks.thematicmapping to com.esri.bacore.thematicmapping. The rampColorsCount property is now writeable. The getColorByValue method now returns a linear gradient color calculated with a palette of currently available discrete colors. The updateColorRamp method has been deprecated and the rampColorsChanged event has been added. The mixColors method has been added.
• The ColorRampSchema class has been moved from com.esri.bao.tasks.thematicmapping to com.esri.bacore.thematicmapping. The mixColors method has been removed and the colorFromHexCode method has been added.
• The Color class has been removed. Colors are now represented with the uint type.
• The ThematicMappingResources class has been removed. The static colorRampSchemas property, providing the default collection of BAO color ramp schemas, has been moved to the ThematicMappingLayer class.

  Classifications

• The core Classification class has been added.
• The Classifier class has been replaced with the core IClassifier interface. The static methods of this class, ensureValidData and getBounds, have been moved to the core Classification class.
• The EqualIntervalsClassifier and QuantileClassifier classes have been moved to com.esri.bacore.thematicmapping. They now implement the IClassifier interface instead of inheriting from the Classifier class.
• The core TMClassification class has been added. It derives from the Classification class and provides a selection of the classification algorithm from the equal-intervals and quantile classification options.
• The ClassificationType class has been moved from com.esri.bao.tasks.thematicmapping to com.esri.bacore.thematicmapping and renamed TMClassificationType.
• The ClassificationResults class has been moved from com.esri.bao.tasks.thematicmapping to com.esri.bacore.thematicmapping. The interface of this class has been redesigned. Available class breaks are now accessible with the new getClassBreakByIndex method. The classBreaks property has been removed and the count property has been added. The minValue and maxValue properties have been renamed with minimumValue and maximumValue, respectively. The valueFormat property has been added.

  Geography levels

• The core GeographyLevels class has been added - providing read-only access to available geography levels and supporting geography levels search by name.
• The GeographyLevelInfo class has been moved from com.esri.bao.tasks.thematicmapping to com.esri.bacore.thematicmapping. The interface of this class has been changed and extended. The geographyLevelAlias and geographyLevelName properties have been renamed to aliasName and name, respectively. The aliasName property is now writeable. The getLayerByIndex, selectBestLayer, and toString methods have been added.
• The GeographyLayerInfo class has been replaced with the core IGeographyLayerInfo interface. This interface has been extended with idField, nameField, and scale properties, and the layerName property has been renamed to name.

  Thematic variables

• The ThematicMappingRendererInfo class has been removed. The functionality of this class has been split in a number of classes.
• The core TMSummarizations class has been added. It maintains the available summarizations and allows you to get summarization info by index or by name of a summarization variable. It provides a default value formatter and default for value precision when a thematic value is calculated as average, percentage or index and is also responsible for creating a value calculator for a summarization variable.
• The core abstract ValueCalculator class has been added. It provides calculation of the thematic value for a graphic by its attributes. It is also responsible for creating a list of value description fields for a graphic by its attributes.
• The core TMValueCalculator class has been added. It derives from the ValueCalculator class and implements calculations of the thematic value by graphic attributes for the given summarization variable and the given value calculation type.
• The TMValueType class has been moved from com.esri.bao.tasks.thematicmapping to com.esri.bacore.thematicmapping. The AVG_BASE and INDEX_BASE enumeration constants have been renamed to AVERAGE and INDEX, respectively.
• The core ValueDescriptionStyle class has been added. Its enumeration constants specify the style of requesting value description fields.
• The core ValueInfo class has been added. It provides proper formatting of values of the thematic and auxiliary variables.

  Thematic layer infrastructure

• The Thematic Layer functionality has been moved from the ThematicMappingLayer class to the new core TMLayer class and to auxiliary classes.
• Working with a thematic mapping query task has been standardized under the new core IQueryTask interface. This interface provides methods to initialize a thematic mapping query task and execute queries for a given geography layer.
• The ThematicMappingQueryResults class has been moved from com.esri.bao.tasks.thematicmapping to com.esri.bacore.thematicmapping and renamed QueryTaskOutput. The interface of this class has been simplified; the envelope and where properties have been removed.
• The core TMAttributesProvider class has been added. It provides a link to the value calculator currently used in the associated thematic layer and grants a number of methods for accessing attributes of a graphic.
• The RendererUpdateEvent class has been replaced with the new core TMLayerChangedEvent class.
• The core TMLayerAvailableEvent and ProgressEvent classes have been added.

Benefits of the New Thematic Layer

• The value calculator is optional for a thematic layer. If it is absent, the thematic layer queries geometries and base attributes while updating but doesn’t calculate thematic values for received graphics. In this case, graphics of thematic layer are rendered with the middle color of the current color ramp.
• The additionalFields property of the thematic layer allows you to specify additional fields to be present in the attributes of graphics received with the query task. The collection of fields requested in a query comprises of three items: the feature ID and feature name fields, fields requested from the current value calculator, and additional fields.
• The geometry extent for a query can be set with the analysisExtent property value. If this value is missing, geography features are requested for the current map extent. Therefore, the thematic layer can work in a static mode when a query extent is specified by a user or in a dynamic mode when a query extent is synchronized with the current map extent and automatically changes when the map extent changes. The combination of these two modes is also allowed if the intersectAnalysisExtentWithMapExtent property value is true.
• Updates of a thematic layer can be automatic or manual. In the auto-update mode (default), a thematic layer is updated when the properties affecting the thematic shading or the map extent are changed. In manual-update mode, a thematic layer is updated with the applyUpdates method only, but changes in the color ramp and border are immediately applied. Using the suspendUpdates method, you can postpone updates in auto-update mode until the applyUpdates method is applied. The autoUpdate property value switches between auto-update and manual-update modes.
• The thematic layer doesn’t change attributes of features received from a map service contrary to the previous version of the thematic layer in which all received attributes were replaced with special descriptive attributes such as “TMVARID”, “TMVARNAME”, “TMVARVALUE”. With the new thematic layer, descriptive attributes of a feature can be composed with the createDescriptionFields method of the TMLayer or TMAttributesProvider class.
• A calculated thematic value appears in attributes of graphics under a special “$TMValue” name specified with the tmValueField property value.
• You can manually execute any query with the thematic layer using the executeQueryTask method. The prepareQuery helper method simplifies creating a query by populating spatial parameters from current geometry settings of the thematic layer.
• Work with the thematic layer is event-driven. The tmLayerChanged event is dispatched when the thematic layer completes updates. Parameters of this event specify the cause of an update. There will be more than one reason of the update if updates were suspended for a period of time.
• A number of the taskProgress events are dispatched while the thematic layer is updating. Every update starts with the progress value of 0, dispatches intermediate values of progress showing an update phase, and completes or fails with the progress value of 100.
• The tmLayerAvailable event is dispatched when the availability of the thematic layer is changed. This can appear when the current scale of the map exceeds a maximum scale available for the geography level used. For example, a user has zoomed out on the map, the event is triggered. When the geography level becomes available again, for example, a user has zoomed in on the map, the event is dispatched again.
• The propertyChange event is dispatched when a property of the thematic layer is changed. Along with changes in bindable properties, this event is also dispatched when a geography level or geography layer is changed.
• The extentChange event is dispatched after the map extent is changed but before the updating of the thematic layer starts.
• The fault event is dispatched when thematic mapping query task fails to execute a query.

Changes in Core Classes

The following changes have been made in the com.esri.bacore package.

• The BAValueType enumeration has been added.
• The valueType property has been added to the SummarizationInfo class. It allows you to specify the type of summarization field to format summarization values with the appropriate units.
• The IValueFormatter interface has been added.
• The ValueFormatter class, the default implementation of IValueFormatter, has been added. It derives from the standard NumberFormatter class. The formatUnits property of this type allows you to specify a method that adds units to formatted values. For example, it can provide a currency-type or percentage-type value with $ and % signs, respectively.
• The ValueFormat class has been added which encapsulates information about the value (value precision and value type) together with the value formatter. This type can be used for formatting edge values of class-break intervals to show them in the classification legend. An instance of this type is provided with the valueFormat property of the thematic mapping core ClassificationResults type.
• The KeyValuePair class has been added. It is used in the array of value description fields returned with the createDescriptionFields method of the TMLayer class.
• The IJsonObject interface has been added. It provides the toObject method that converts a data type to the Object type instance. All complex core data types now implement this interface.
• The PointRecord class has been extended with the storeAddress property. This property value is not used in the current version of Business Analyst Online API but is used in the Business Analyst Server API which shares this data type with Business Analyst Online API.
• The StdGeographiesFeature class has been added. It derives from the IDNamePair class and adds two attributes, stateAbbreviation and stateName, which are currently not used in the Business Analyst Online API.

Changes in Business Analyst Online Tasks

Tasks of the com.esri.bao.tasks.stdgeographies package now return an array of items of the StdGeographiesFeature type. Since this type derives from the IDNamePair class, you don’t need to make any change in your code; this change is backward compatible.