Map and layers overview

This topic introduces the map control, map layers and the basic map attributes, such as spatial reference, initial extent, and layer visibility.

The map control is a Swing component that allows you to embed a 2D map inside your Java application. It can display multiple map layers of geographic information and allows you to pan or zoom around the map or click on features to explore their attributes.

You can add a range of online, local, static or dynamic layers to the map control as well as specialized layers for working with data such as Global Positioning System (GPS), temporal, Bing or OpenStreetMap. For better display performance, it is important to consider the nature of the data (static or dynamic), the layer order and the spatial reference before using the map control. For step-by-step instructions on creating a map control, see the topic How to create a map control.

Map layers

Map layers can be grouped into one of three main types:

Basemap layers

A map layer that gives visual context to an application is called a basemap layer. These layers are tiled map services that supply a pre-rendered, seamless, continuous map with a tiling structure that is designed for fast performance as the tile structure is independent of the detail or complexity of the map. An important factor is that a basemap layer contains data that does not change frequently, such as topography, imagery or streets, as the tiles have to be pre-built and cached. ArcGIS Online provides a free set of ready-to-use basemap layers that are pre-rendered and cached to ensure they will draw quickly. If you need to create your own tiled map services, these can be created using ArcMap as the authoring tool.

Operational layers

Operational layers supply data that can be queried to perform both decision-making and task-based functions. Because the data supporting operational layers may change frequently, operational layers are usually served from a spatial data source (e.g. a file geodatabase). These layers may contain the results from an analysis, features that require editing, or new data that needs to be made available to map application users.

Graphics layers

If your application needs live or temporary data such as a vehicle's location, events, query results or user interaction, then store the information in a graphics layer (GraphicsLayer). You can easily manipulate the geometry, set the attributes and change the symbol of each graphic in the graphics layer. This layer is well suited to applications that display a lot of rapidly moving graphics. Be aware that the graphics are in memory on the client side and their performance is directly dependent on both the number of graphics and the complexity of their rendering.

Layer order

It is recommended to divide all of your layers into the three types described above. Live, rapidly changing, ephemeral data should be stored as graphics. Frequently changing data, layers for editing, or the results of analyses should be served as operational layers. Background data that does not change often should be served as a basemap. This is a major consideration when maximizing the performance of your application.

A basemap layer should be added to the map first. This will ensure that it is positioned at the bottom of the map and will not hide other layers. The first layer will define the map's spatial reference if it has not been defined using the setSpatialReference method. The basemap and map should have identical spatial references because a tiled map service cannot be re-projected. Operational layers should be added to the map next and the graphics layers added last.

Layer visibility

The visibility of a layer is handled by a number of basic operations. You can:

Spatial reference

The map control has a single spatial reference that is set when the first layer is added to the map. The map cannot change its spatial reference once it has been set. Also, note that the map control cannot re-project layers that are rendered as static tiled map services. So if any tiled layers are going to be added to the map, they must have the same spatial reference. Dynamic map service layers, feature layers and graphics layers can re-projected to the spatial reference of the map but we recommend that these layers also have the same spatial reference as the map otherwise a performance overhead will be incurred by the re-projection process.


The first layer in a map will define the map's full extent. You can override this by setting the map's full extent property and if required you can also define the current extent of the map to ensure the user starts in a familiar location. Read more about setting the extent in the topic Navigating the map.

Interacting with the map

Actions such as clicking mouse buttons, dragging the cursor and rolling the mouse wheel allow users to pan and zoom the map contents and to explore attributes of individual features. This mouse interaction happens by default because the mouse events are captured by the MapOverlay class. If you wish to alter, block or enhance these mouse interactions you can do so by extending the mouse events defined in the MapOverlay class. For example, if you wish to add your company logo onto the map control, you can extend the MapOverlay class and override the onPaint method to have it draw the logo each time the map is painted. If you add overlays to the overlay stack, this can block events lower down the stack so it is important to design this carefully in order to achieve the correct behavior.