ArcGIS Runtime SDK for Android

Migrate to 100.x from 10.2.x

When you compile your unchanged 10.2.x application code against 100.x libraries for the first time, you will see compilation errors. Conceptually, you'll need to consider 100.x as a different product from the previous versions of ArcGIS Runtime. In reality, it is the same product, but it will best serve you to think about it as a different API, at least from the beginning. The way in which your workflows are achieved has been re-designed in many cases to fit better with the ArcGIS platform and the Web GIS model as it has evolved today.

This topic outlines areas of the API that have undergone considerable changes and to provide guidance for re-factoring 10.2.x code for a 100.x app. Although this topic doesn't cover every change, it will help you get over some major migration hurdles. It will also help you decide whether functionality required for your app is available in 100.x.

Functional changes

In many cases where functionality appears to be missing from 100.x, it is available but has been implemented differently. These changes require you to change your code to use new programming patterns or classes. The following sections describe some of the functional areas of the API where these types of changes have been implemented.

Maps

The Map object has been split out from the view that displays it, to represent the model or viewmodelcomponent in a Model-View-Controller (MVC) or Model-View-ViewModel (MVVM) architecture. These important objects are at the heart of the ArcGIS Runtime and have an API that follows the ArcGIS Web GIS information model. They contain operational layers, basemaps, bookmarks, pop-ups, and other ArcGIS-specific data to be leveraged in your apps. They also include APIs to instantiate maps from URLs, portal items, or default basemaps. For details on how to add views and maps to your 100.x apps, see Build a new map.

Views

The GeoView interface, implemented by MapView, is solely responsible for display and interaction, separating concerns from model objects, e.g. ArcGISMap. The Views contain graphics overlays, as well as operations, to easily identify features and graphics without having to write any layer type specific code. There is a lot you can control with the GeoView.

Loadable

The Loadable interface was introduced at 100.0.0. Its design and purpose is intended for those workflows that involve accessing lots of data over the wire from connected online resources. All resources that load metadata asynchronously to initialize their state (such as maps, layers, and tasks) adopt the loadable pattern. The loadable pattern makes the behavior of loading state more consistent and explicit. Loadable resources do not automatically load their state. They load lazily when loaded by your app code or loaded by other objects that depend on them. This becomes useful for cases where, for example, you need to obtain information from a map resource without having to visualize it first. You can explicitly load the map resource without first associating it to a map view. The status of a loadable resource is easy to monitor to determine whether it is loading, has loaded successfully, or has failed to load. Your app can retry loading it if the resource failed to load due to a transient or recoverable condition.

Common use cases for using Loadable are explained and demonstrated through code examples in the Loadable pattern topic.

If 10.2.x versions of your apps performed editing tasks involving feature services, it's important for you to understand clearly the new loadable pattern. For example, retrieving features from an ArcGISFeatureTable return ArcGISFeature objects which implement the loadable pattern for increased efficiency. When getting ArcGISFeature objects for rendering and query purposes, a minimum set of required fields is returned, such as identifiers, geometry, fields used for symbolizing, and so on. You must first load the feature that you want to edit; otherwise, the edit operation will fail. For complete details and code examples of loading features in editing workflows, see the Edit features guide topic.

Graphics overlays and graphics

Graphics are used to display temporary or ad-hoc geographic data on top of a map. In 10.2.x, you added graphics to your map using a GraphicsLayer. Graphics are now added to GeoViews as overlays. This ensures that graphics are always displayed on top, even when map layers are reordered. This also makes it convenient to switch out maps while keeping the graphics in place.

The guide topic Add graphics overlays to your app provides code for creating graphics overlays and adding them to the map. You can see the code for adding and working with graphics in a graphics overlay in Add graphics and text to graphics overlays.

Also at 100.x, there is a simpler pattern for identifying graphics within graphics overlays. The identifyGraphicsOverlayAsync method on GeoView (MapView or SceneView) identifies visible graphics in the specified graphics overlay, near the provided screen point. The Identify Graphics code example demonstrates the usage of this method.

Feature tables

ServiceFeatureTable now has a FeatureRequestMode that is like the 10.2.x Mode property (Snapshot or OnDemand). The value determines how features are requested from the service for use in the client.

  • On Interaction with Caching - Features are requested and stored in the table when needed based on user interaction (panning or zooming to different extents, for example). Features are cached to reduce the number of requests for features.
  • On Interaction without Caching - Features are always requested from the service. There is no caching of features, so this consumes the largest amount of network bandwidth.
  • Manual Caching - Features are only requested when explicitly requested by the app. All queries are made to the local version of the data.

Offline

The APIs for common operations such as editing, searching, geocoding, or routing are the same whether you are online or offline. This is one of the big differences to keep in mind at 100.x. Also, with respect to packaging Offline maps, ArcGIS Pro comes center-stage with the ability to create and share offline mobile map packages. A Mobile Map Package (.mmpk) is a set of items bundled together for transport, often for use in offline workflows. The items are one or more maps, their associated layers and data, and optionally networks and locators. A mobile map package also includes metadata about the package that you can glean useful information from using the new API. You don't need a Local Server to access these packages.

Check out the MobileMapPackage class in the API reference and the Create an offline map topic for a thorough description of how to create and work with Mobile Map Packages. There is a helpful code sample for opening and using mobile map packages as well.

You can also take your connected ArcGIS based feature and tiled layers offline on demand with dedicated tasks and associated jobs, just as you were able to with previous versions. However, you might find that the class names and methods differ slightly from previous versions. The GeodatabaseSyncTask works with ArcGIS feature services to take features offline in a mobile geodatabase (.geodatabase file) and allow them to be edited and synced. The ExportTileCacheTask extracts tiles from a tiled ArcGIS map service as a tile package (.tpk file) and allows them to be viewed offline.

The Edit features guide topic provides code examples and in-depth discussion for editing both online and offline with the new API.

Authentication

All security and authentication related aspects are managed by a new AuthenticationManager class which helps to unify and centralize how authentication is performed, regardless of the security solution in place. It allows the developer to decide how much control to exercise over authentication-related events handled by an app. It also caches credentials by default, reducing the number of times a user is prompted for credentials. The authentication manager issues an authentication challenge whenever authentication-related events occur. Developers can monitor these challenges and respond with appropriate credentials to get access to secured resources, or allow the authentication manager to prompt the end user for credentials.

Portal

The mapping API has been refactored for better integration with the portal API. This API allows you to load maps stored in a portal (web maps) into your app, make updates to web maps, and save changes back to the portal item. Also, your app can save maps created by your app as a new portal item. These web maps can then be used elsewhere within the ArcGIS system.

The concepts and code examples for displaying a web map by ID are covered in Display a map. You can also access a web map and it's contents without the need to display it, as described in Access portal content. Also in this topic, you'll find useful examples of how to fetch thumbnails of times, access portal item data, and list the groups that a user belongs to.

The Save a map topic provides great examples for using the new map saving capabilities. Also, see the Create and Save a Map sample for code examples.

Error handling

With 100.x, it's easier to determine where errors occur in the stack so you can provide better error messages to your Runtime app users. A new standardized error domain property indicates whether the error occurred client-side within the ArcGIS Runtime, or server-side from an ArcGIS Server service or web service. A consistent error code property can be used to further diagnose the error's cause or determine what error message should be displayed to the user. For a complete list of error domains and codes, see the Platform error codes topic in the guide.


In this topic
  1. Functional changes