Skip To Content ArcGIS for Developers Sign In Dashboard

Local Server

Local Server, an optional component of ArcGIS Runtime SDK for Java, is primarily for executing offline geoprocessing tasks in your ArcGIS Runtime apps. These tasks work in the same way as geoprocessing tasks published from ArcGIS Online or ArcGIS Enterprise. Running a geoprocessing task on Local Server requires an ArcGIS Pro or ArcMap geoprocessing package (.gpkx or .gpk file). These packages are authored in ArcGIS Desktop either using Model Builder or by writing a Python script. See Author and publish a geoprocessing model for details on publishing geoprocessing packages.

Local Server also allows developers to consume map image layers or feature layers from content in an ArcGIS Pro or ArcMap map package (.mpkx or .mpk file). These packages are authored and created using ArcGIS Desktop. This capability has been included to support workflows in earlier versions of ArcGIS Runtime. If you're starting a new project and require offline data, use sync-enabled geodatabases, which are generated from feature services.

Local Server can be downloaded for Windows (32- and 64-bit) and Linux platforms (64-bit). Local Server is not supported on macOS.

To develop with Local Server, you must set up your development environment's access to it. To deploy your app with Local Server capabilities, you must set up your app's access to the Local Server.

Before you use Local Server capabilities, you must start the Local Server instance.

Installing the Local Server SDK

Install Local Server on Windows

  1. Ensure that your development machine meets the system requirements for ArcGIS Runtime Local Server SDK Java. Development and deployment machines must also have the following packages installed:
    • Microsoft Visual C++ Redistributable for Visual Studio 2017
    • Development and deployment on Windows 8.1, Windows Server 2012, Windows Server 2012 R2, or Windows 7 SP1 also requires installation of the Windows 10 Universal C Runtime via the following Windows Updates or Update Packages:
      • Update for Windows 8.1 (KB2999226)
      • Update for Windows 8.1 for x64-based Systems (KB2999226)
      • Update for Windows Server 2012 R2 (KB2999226)
      • Update for Windows Server 2012 (KB2999226)
      • Update for Windows 7 (KB2999226)
      • Update for Windows 7 for x64-based Systems (KB2999226)
  2. Download Local Server from the Downloads page. You'll need to log in with an ArcGIS developer account. Sign up for a free account if you haven't already. Save the file to a location on your development machine.
  3. Extract the file you downloaded, and then double-click the Setup.exe file to start the installation wizard.
  4. Follow the instructions. In the Destination Folder dialog, you can change the default installation directory by clicking the Change button, then navigating to the desired folder. Make sure you have write permissions to this folder on your development machine. Ensure no other users are using the folder.
  5. On the last panel of the wizard, click Finish. The ArcGIS Runtime Local Server is now installed at the installation folder you chose in the previous step.

Install Local Server on Linux

  1. Make sure your development machine meets the system requirements for ArcGIS Runtime Local Server SDK Java.
  2. Download Local Server from the Downloads page. You'll need to log in with an ArcGIS developer account. Sign up for a free account if you haven't already. Save the file to a location on your development machine.
  3. Unzip the ArcGIS Runtime gzip file to get the tar file. At the prompt, type gunzip .tar.gz.
  4. Extract the product .tar file to create the installation directory: tar xvf .tar.
  5. Follow the on-screen instructions. In the Choose Install Folder dialog, you can change the default installation directory by clicking the Choose button, and then navigating to the desired directory. Make sure this directory is on your development machine and that you have write permissions to this directory. Ensure no other users are using the directory.
  6. On the last panel of the wizard, click Done. Local Server is now installed in the installation directory you chose in the previous step.
  7. If you are using an Enterprise Geodatabase connection which uses ODBC (SDE connection to netezza for example) you will need to modify init_user_params.sh to uncomment the following line:
    #
    # Enable this section to point to the native ODBC driver.  Note the path
    # may be different on your system. 
    #
    #export LIB_ODBC_DRIVER_MANAGER=/usr/lib64/libodbc.so.2
    The exact path may differ depending on your installation, and you may need to install the unixODBC-utf16-2.3.1-1.x86_64 or later library.
Note:

If you see Fontconfig error: Cannot load default config file on the console, Local Server cannot find fonts on your machine. Set the FONTCONFIG_PATH environment variable either in /etc/profile or explicitly—for example, export FONTCONFIG_PATH=/etc/fonts.

Installing database client software for enterprise geodatabase connections

If any of your Local Server packages make use of enterprise geodatabase connections (SDE), then you may need to install the client software for the database you are connecting to. The section on Database connections gives details on the configuration of database client software.

Set up your app's Local Server directory

As a developer, when you have installed the Local Server SDK, your applications that use Local Server will work because they'll use the installation directories referenced in the RUNTIMELOCALSERVER_100_0 Environment variable.

However when you deploy your application, you need to make the Local Server binaries available to your application in one of the following ways. The Local Server binaries for 32-bit platforms are in the 32 directory, and 64-bit binaries are in the 64 directory.

  • If you have not done so already, create a Local Sever deployment.
  • Copy the Local Server directory so that it is adjacent to your application executable file (so that the 32 or 64 folder is at the same level as your app's executable file).
  • Set your own custom location for the Local Server directory using the LocalServer.INSTANCE.setInstallPath("c:/myLocalServerInstall"); method and be sure to install the Local Server folder there as part of the app install.
  • You can set up your own RUNTIMELOCALSERVER_100_0 environment variable pointing to the Local Server directory; although this is typically used as a developer workflow.

Start a Local Server instance

You must start a Local Server instance if you want your app to use any services on the Local Server. Only one instance of the Local Server can be running at any time.

  1. Prior to requesting Local Server to start, it's good practice to check that your application can access the Local Server installation path.
    // check that local server install path can be accessed
    if (LocalServer.INSTANCE.checkInstallValid()) {
      server = LocalServer.INSTANCE;
      // ... place code to start local server
    
    
    } else {
      Platform.runLater(() -> {
        Alert dialog = new Alert(AlertType.INFORMATION);
        dialog.setHeaderText("Local Server Load Error");
        dialog.setContentText("Local Server install path couldn't be located.");
        dialog.showAndWait();
    
    
        Platform.exit();
      });
    }
  2. Once you have a valid Local Server directory, start the process.
    // start local server
    server.startAsync();
    // watch server status
    server.addStatusChangedListener(status -> {
      System.out.println("Server Status: " + status.getNewStatus().toString());
    });
  3. Once the Local Server has started, you can start services (such as geoprocessing services, for example) as described in the following sections.
  4. When an application is closed down, the Local Server should also be shut down by calling stopAsync.
    // stop local server
    if (LocalServer.INSTANCE.getStatus() == LocalServerStatus.STARTED) {
      LocalServer.INSTANCE.stopAsync();
    }
  5. The sample application in GitHub shows how to start and stop the Local Server.

Run geoprocessing services

Geoprocessing services can be used from Local Server with a geoprocessing package file (.gpkx or .gpk file). The geoprocessing packages are authored and published using ArcGIS Pro or ArcMap. When preparing a geoprocessing package with ArcGIS Pro, use the Package Result tool and be sure to check the Support ArcGIS Runtime box in the Parameters pane. If this box is not checked, the .gpkx file will not run as a Local Server service. For more information about geoprocessing, see Run a geoprocessing task.

A local geoprocessing service can be started provided that the Local Server is started. The following code shows how to start the service and set up a task to use the "Message in a bottle" sample geoprocessing package.

// start local geoprocessing service once local server has started
server.addStatusChangedListener(status -> {
  if (status.getNewStatus() == LocalServerStatus.STARTED) {
    try {
      String gpServiceURL = new File("./samples-data/local_server/Contour.gpk").getAbsolutePath();
      // need map server result to add contour lines to map
      localGPService =
        new LocalGeoprocessingService(gpServiceURL, ServiceType.ASYNCHRONOUS_SUBMIT_WITH_MAP_SERVER_RESULT);
    } catch (Exception e) {
      e.printStackTrace();
    }


    localGPService.addStatusChangedListener(s -> {
      // create geoprocessing task once local geoprocessing service is started
      if (s.getNewStatus() == LocalServerStatus.STARTED) {
        // add `/Contour` to use contour geoprocessing tool 
        GeoprocessingTask gpTask = new GeoprocessingTask(localGPService.getUrl() + "/Contour");
      }
    });
    localGPService.startAsync();
  }
});

When running geoprocessing tools in the context of local server, the recommended approach for output data is to write the output data to a specific location on the local file system determined by the application or by the script/model and access the data directly from that location instead of returning a parameter of type GeoprocessingDataFile and using its fetchFileAsync function to return the content via http, which is usually less efficient. To do this, take one of the following approaches:

  • Expose an input parameter in the script/model representing the path where the output should be written to the local file system. The application code would then calculate/derive the location and pass that into the tool input parameters.

  • Calculate/derive a path within the script/model where the output will be written to the local file system and return that as a parameter in the script/model. The application code would then retrieve the location form the tool output parameters.

To learn how to use ArcGIS Pro to create a geoprocessing result that can be shared as a geoprocessing package, try the DevLab.

Run map image layer services

Map services can be consumed from Local Server using a map package file. Provided that the Local Server is started, you can start a service. Once the service is started, the URL is obtained and used to add an ArcGISMapImageLayer to your map.

// start map image service
String mapServiceURL = new File("/path/to/file.mpk").getAbsolutePath();
LocalMapService mapImageService = new LocalMapService(mapServiceURL);
mapImageService.addStatusChangedListener(status -> {
  // check that the map service has started
  if (status.getNewStatus() == LocalServerStatus.STARTED) {
    // get the url of where map service is located
    String url = mapImageService.getUrl();
    // create a map image layer using url
    ArcGISMapImageLayer imageLayer = new ArcGISMapImageLayer(url);
    // set viewpoint once layer has loaded
    imageLayer.addDoneLoadingListener(() -> {
      if (imageLayer.getLoadStatus() == LoadStatus.LOADED && imageLayer.getFullExtent() != null) {
        mapView.setViewpoint(new Viewpoint(imageLayer.getFullExtent()));
      }
    });
    imageLayer.loadAsync();
    // add image layer to map
    mapView.getMap().getOperationalLayers().add(imageLayer);
  }
});
mapImageService.startAsync();
Example of ArcGISMapImageLayer from a local map service.

Run feature services

Feature services can also be consumed from a Local Server instance. As with map services, these services use a map package file (.mpkx or .mpk) that has been authored and published from ArcGIS Desktop.

The code below shows how to start the service, obtain the URL, and use this to add a feature layer to the map.

// start feature service
String featureServiceURL = new File("path/to/file.mpk").getAbsolutePath();
LocalFeatureService featureService = new LocalFeatureService(featureServiceURL);
featureService.addStatusChangedListener(status -> {
  if (status.getNewStatus() == LocalServerStatus.STARTED) {
    // get the url of where feature service is located
    String url = featureService.getUrl() + "/0";
    // create a feature layer using the url
    ServiceFeatureTable featureTable = new ServiceFeatureTable(url);
    featureTable.loadAsync();
    FeatureLayer featureLayer = new FeatureLayer(featureTable);
    featureLayer.addDoneLoadingListener(() -> {
      if (featureLayer.getLoadStatus() == LoadStatus.LOADED && featureLayer.getFullExtent() != null) {
        mapView.setViewpoint(new Viewpoint(featureLayer.getFullExtent()));
      }
    });
    featureLayer.loadAsync();
    // add feature layer to map
    map.getOperationalLayers().add(featureLayer);


  }
});
featureService.startAsync();

Manage local services

When using the Local Server you are effectively a server administrator. You choose which services to create, determine the server-side properties of the services, and manage the service life cycles. Unlike online services, where all the service parameters are predefined by the service publisher, you must specify the local service settings via the API based on how your app needs to interact with the local service.

The API provides a class to represent each service type, allowing you to set the source content, such as a map or geoprocessing package; set the service properties; and manage the service life cycle by starting and stopping the service as required by your workflow. Services must be set up with the appropriate package type to begin with, and then they can be started. Once the service has started, you can obtain its URL and use it in other API classes such as layers and tasks. For example, you can use the URL of a local map service to create an ArcGISMapImageLayer. If your app no longer requires the service, you can choose to stop specific services via the API, which will allow the system to reclaim any memory used by those services.

When creating local geoprocessing services to run geoprocessing tools and models, you must choose whether the service will run synchronously (Execute), asynchronously (SubmitJob), or asynchronously with a dedicated local map service instance to draw the result (SubmitJobWithMapServerResult). Once the service is running, it is not possible to change the execution type. Note that although the terms synchronous and asynchronous are used, these actually refer to the internal infrastructure the Local Server uses to manage these services, and from an API perspective the execution is always asychronous. The decision is typically based on the type of analysis or processing that will be performed and the result type. If the tool will take less than a few seconds to run, the Execute type is recommended. If the tool will take longer and you would like to be able to determine the progress via the API, and perhaps report this to the user, the SubmitJob type is recommended. In some cases, your analysis might return such a large number of features that it would be inadvisable to obtain the features directly and display them as graphics, and better to instead render them in a result map service. Additionally, raster datasets and raster layers are not directly supported as output data types and instead must be rendered in a result map service. In both these latter cases, you should choose the SubmitJobWithMapServerResult execution type.

The following code shows how to start a local geoprocessing service programmatically.

// get a url to the local geoprocessing package
String gpServiceURL = new File("./samples-data/local_server/Contour.gpk").getAbsolutePath();

// create a local GeoProcessing service from the url
localGPService = new LocalGeoprocessingService(gpServiceURL, ServiceType.ASYNCHRONOUS_SUBMIT_WITH_MAP_SERVER_RESULT);

Once started, the Url of the LocalGeoprocessingService can be used to create a Geoprocessing task.

localGPService.addStatusChangedListener(s -> {
  // create geoprocessing task once local geoprocessing service is started 
  if (s.getNewStatus() == LocalServerStatus.STARTED) {
    // add `/Contour` to use contour geoprocessing tool 
    gpTask = new GeoprocessingTask(localGPService.getUrl() + "/Contour");
  }
});
localGPService.startAsync();

Local Server Utility

Just as with full server and online services, there are times when you would like access to additional information on services running in the Local Server and also information on the interaction between the API and the service. The ArcGIS Runtime API and Local Server provide facilities for this. It is important here to make a distinction between the Local Server instance within the SDK installation the API uses by default versus a Local Server deployment. The instance included with the SDK installation includes all the components and has several features enabled that can help you debug local services, whereas a deployed instance of the Local Server has debugging options disabled by default to minimize the disk footprint and to ensure the security of the Local Server.

Debug settings are administered via the Local Server Utility application. This is automatically included in the SDK instance of the Local Server but must be explicitly included in a deployment when specifying options in the deployment builder. The Local Server Utility provides you with the ability to control how apps work with the Local Server. You can specify logging to help debug ArcGIS Runtime issues, select port range to avoid conflicts, delete temporary files, and provide error reports.

The Local Server Utility can be found in the Local Server installation folder. For example: C:\Program Files (x86)\ArcGIS SDKs\LocalServer100.x\64\bin\LocalServerUtility.exe

ArcGIS Runtime Local Server utility application window.

ArcGIS Runtime REST services directory

Local Server provides a services directory like the ArcGIS Services Directory available with online services. This provides a user-friendly HTML view of the service metadata JSON. You can use the HTML service definition and task pages to discover how to code against your services.

The services directory can be accessed via the Local Server URL and can be viewed in a browser to explore service parameters. The Local Server instance in the SDK installation by default includes the HTML server pages, while a deployment of the Local Server does not. This setting is controlled via the Local Server Utility (Generate HTML Server Pages checkbox). Another setting in the Local Server Utility that determines how you work with the services directory is the Add Random Prefix to Server URLs option. If disabled, the Local Server will have a predictable URL each time it is started by your application, making it easier for you to work with the services directory between debugging sessions. Although local services cannot be accessed outside the local machine, the random prefix option was added to provide additional security from applications running on the local machine.

ArcGIS Runtime REST Services Directory.

Supported raster formats

Local Server supports the raster dataset file formats supported by ArcGIS Desktop.