Workflow: Using ArcGIS Spatial Data Server for the Java Platform to serve database data

Complexity: Beginner Data Requirement: Use your own data

You can set up ArcGIS Spatial Data Server for the Java Platform and publish data from your existing database by following the example presented in this topic.

In this example, an application will be created to collect demographic information on college alumni for a specific college. The college can use the information collected to market their college to prospective students or can be used to help prospective students plan for their education: which schools and majors offer the best return on investment (cost of attending vs. expected salary after graduation).

A region feature class using PostGIS geometry storage in a PostgreSQL database will be published as an editable feature service to the spatial data server. The region feature class shows postal code zones to represent roughly where alumni are now living.

Deploy a spatial data server

You must install ArcGIS Spatial Data Server for Java, the JDBC provider, a database management system (DBMS) client, and a Java application server.

After that, configure the data source.

Install ArcGIS Spatial Data Server for Java

To install ArcGIS Spatial Data Server for Java, follow the instructions in the installation guide provided with the software. This guide includes information about system requirements, authorization, and installation of the software.

Note:

To allow editing through your published services on ArcGIS.com, you must install ArcGIS Spatial Data Server on a public server (one outside your firewall).

Install JDBC providers and set up a Java application server

Download and install the supported JDBC driver for your DBMS and an application or web server.

In this workflow, the PostgreSQL JDBC file and Tomcat are installed.

Steps:

1. Download the PostgreSQL JDBC driver from http://jdbc.postgresql.org/download.html and place it on the server where ArcGIS Spatial Data Server and Tomcat are installed.
2. Download Tomcat from the Apache Software Foundation site.
3. Install Tomcat on your server.
4. Copy the PostgreSQL JDBC driver to the Tomcat lib directory.

Configure the data source

You must configure your data source with your web or application server.

For this workflow, alter the Tomcat context.xml file to configure your data source.

Steps:

1. Open the context.xml file in the conf directory where Tomcat is installed.
2. Edit the <Resource name> section of the file, providing information for your PostgreSQL database cluster.

   In this example, the data source name is postgres, the database cluster is listening on the default port 5432, and the database is gisdata. The connection is being made as the login role alumapp.

   <Resource name="jdbc/postgres" auth="Container"
                 type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
                 url="jdbc:postgresql://127.0.0.1:5432/gisdata"
                 username="alumapp" password="ruL00king" maxActive="20" maxIdle="10" 
                 maxWait="-1"/>

3. Save the context.xml file.

Prepare accounts

Since the data published as a feature service will be edited, you must grant editing privileges to the user who connects to the data and publishes it. You will also be publishing to ArcGIS Online, so you must create an ArcGIS Online account.

Grant privileges to the connecting user

When you get to the next set of steps, you will specify a user to connect when registering the data source. That user must be granted privileges on the datasets you want to publish to the spatial data server. For example, if you want users to have select only access to the data in your feature service, the user specified for the data source only needs to have select privileges on the datasets in the feature service.

In this workflow example, the feature service will allow select, add, and update privileges; therefore, the user connecting to the data source must be granted select, insert, and update privileges on the customers feature class. In addition, since the feature class uses PostGIS geometry storage, the user must be granted privileges on the public.geometry_columns and public.spatial_ref_sys table.

As shown here, a database login role and schema, alumapp, are created. The login role is granted select, insert, and update privileges on the regions feature class in the database, as well as select, insert, update, and delete on the geometry_columns table and select privileges on the spatial_ref_sys table. Be sure you are connected to the correct database when you create the schema and grant privileges.

CREATE ROLE alumapp LOGIN 
  ENCRYPTED PASSWORD 'ruL00king', 
  NOSUPERUSER CREATEDB INHERIT NOCREATEROLE;
  
CREATE SCHEMA alumapp AUTHORIZATION alumapp;

GRANT ALL ON SCHEMA alumapp TO alumapp;
GRANT USAGE ON SCHEMA alumapp TO authusers;

GRANT SELECT, INSERT, UPDATE, DELETE  
  ON TABLE public.geometry_columns 
  TO alumapp;

GRANT SELECT
  ON TABLE public.spatial_ref_sys
  TO alumapp;

GRANT SELECT, INSERT, UPDATE
  ON market1.regions
  TO alumapp;

Set up an ArcGIS Online account

In this example, the service will be published to ArcGIS Online, where an application will be created.

You use your Esri Global Account to sign in to ArcGIS Online. You can register your existing Esri Global Account with ArcGIS Online or create an Esri Global Account and register it from the same place. Go to http://www.arcgis.com/home/ and click Sign In.

If you have already registered your Esri Global Account with ArcGIS Online, you do not need to sign in at this time. This will be done later in the workflow when the service is published.

Create an administrator connection to the spatial data server

You publish data through a specific connection to the spatial data server. The administrator connection allows you to adminster the server and publish services.

Since you might also want to administer your spatial data server, create an administrative connection to your spatial data server from ArcGIS for Desktop.

Steps:

1. Start ArcMap and open the Catalog window.
2. In the Catalog tree, expand the GIS Servers node.
3. Double-click Add ArcGIS Server.
4. Choose Administer GIS server, and click Next.
5. In the Server URL text box, type the administrative URL of the spatial data server.

   For this example, the URL is http://pub5:8080/arcgis/admin.

6. Choose Spatial Data Server from the Server Type drop-down list.
7. If you will be using this connection to create and save service definitions, you can choose where the service definition files will be staged on disk. By default, they are staged in a folder on your local machine.
8. Click Finish to create the connection.

   Your new connection is listed under the GIS Servers node.

Publish a feature service

You will connect to the database from ArcGIS for Desktop as the same user for which you configured the data source. Next, you will create a map that contains the data you want in your service, map a data source, and publish.

Connect to the database from ArcGIS for Desktop

You make a connection to your database so you can access the data in it. To make a connection to the database, you must install the database client on the computer where ArcGIS is installed.

For this workflow, you need to place the PostgreSQL client files in the bin folder where ArcGIS for Desktop is installed.

Steps:

1. Download the PostgreSQL 32-bit client library files for Windows from the Esri Customer Care Portal.
2. Place the files in the ArcGIS for Desktop bin folder.

Once the PostgreSQL client libraries are in the ArcGIS for Desktop bin folder, you can make a connection from ArcMap to your database.

Connect to your database from ArcMap so you can add the regions table to your map.

Steps:

1. In the Catalog tree, expand the Database Connection node.
2. Double-click Add Database Connections.
3. Type the PostgreSQL server name in the Instance text box.
4. Type the database name, gisdata, in the Database text box.
5. Choose Database authentication from the Type drop-down list.
6. Type alumapp in the User name text box.
7. Type the password for the alumapp login in the Password text box.
8. Leave Save user name and password checked, and click OK.

Author a map

Add the regions table to ArcMap by dragging it from the database connection to the map window.

If ArcMap cannot detect the spatial reference or a qualifying ObjectID column (a not null integer column), you will be prompted to provide that information.

Note:

You cannot publish data that does not have a spatial reference.

Once the table appears in the ArcMap table of contents, symbolize the features using simple symbols that you want to appear in the service. See the ArcGIS help for information on how to change symbology.

Next, make any configuration changes in the map document needed for the properties you want to expose in the service. For example, you will likely want to set which fields will be visible through the service, set aliases for the fields that will be visible, and possibly set some fields as read-only. For this example, you would also want to set up an HTML pop-up menu for users to provide the information needed to process their request. See A quick tour of authoring feature services for a spatial data server for a list of possible properties.

Zoom to the initial extent you want your service to use. You want to be sure that the initial extent will return no more than the maximum number of features you set at the time of publishing for the service to return. By default, that number is 1000. Save your map.

Map the data source and publish an editable feature service

Now that your map is ready, share your data as a feature service by publishing it.

At the time of publishing, you will map the data source.

Tip:

Alternatively, you could have mapped the data source from the REST admin view. See Data source mapping from the REST view for ArcGIS Spatial Data Server for Java for information.

Steps:

1. In your ArcMap document, choose File > Share As > Service from the main menu.
2. In the Share As Service window, there are three options.
   • To immediately publish your data, choose Publish a service and click Next.
   • To save a service definition file to be published later, choose Save a service definition file and click Next.
   • To replace an existing service, choose Overwrite an existing service and click Next. To replace a service, the original service must be stopped first.
3. Choose your admin spatial data server from the connection drop-down list.
4. Type alumni_data in the Service Name text box, and click Continue.
5. Click Feature Access in the Service Editor.
6. Leave all four operations checked since connecting user will be able to query, create, update, and delete data through the feature service.
7. Click Sharing.

   The ArcGIS Online Sign In dialog box opens.

8. Type your Esri Global Account user name and password and click OK to sign in and close the sign in dialog box.
9. In the ArcGIS Online pane of the Service Editor dialog box, check the appropriate box for whom you want to be able to access your content.
   • If you are the only one to access the service for now, check My Content.
   • If you want everyone who has access to ArcGIS Online to see the service, check Everyone (public).
   • Any groups of which you are a member are listed. If you want to grant access to your service to any of these groups, check Members of these groups, then check all groups you want.

   You can check more than one option. For example, you might want the service to be part of your content and grant access to specific ArcGIS Online groups.

10. Click Analyze.

    If you did not already map the data source, you will receive the error message Layer's data source has no mapping. This and any other error must be corrected before you can publish successfully.

11. To correct errors, right-click them.

    The context menu contains links to tools to correct the problem.

12. To correct the data source error, follow the instructions provided in the error help link.
13. Correct any other errors that were returned before proceeding.
14. If you want to see how the feature class will look in the service, click Preview.
15. Click Publish.
16. When publishing completes, click OK to close the dialog box.

View your services

You can view information about your service from the ArcGIS Spatial Data Services Directory. Since you published your service to ArcGIS Online, you can view the service on a map from there.

Access the service from the ArcGIS Spatial Data Services Directory

The ArcGIS Spatial Data Services Directory lists all services published to a specific spatial data server. From here, you can export your service definition as a JSON file, write SQL queries to select or insert features to the feature class, or open your service in ArcGIS.com.

The URL for the ArcGIS Spatial Data Services Directory is http://<server name>/<spatial data server name>/rest/services. Therefore, for this example, the URL is http://pub5:8080/arcgis/rest/services. You will see both services listed.

Use ArcGIS Online

Now that you have published the feature classes to your spatial data server, you can view them from ArcGIS Online.

Steps:

1. Open a web browser and go to the ArcGIS Online website at http://www.arcgis.com/home/index.html.
2. Click Sign In.
3. Type your Esri Global Account user name and password and click Sign In.
4. Click My Content.
5. Add the alumni_data service.
   1. Click Add Item.
   2. Choose An ArcGIS Server Web Service from The item is drop-down list.
   3. Type the URL to the service.

      For this example, the URL is http://pub5/arcgis/rest/services/alumni_data.svc.

   4. Type a title for your service in the Title text box.
   5. Type tags to identify your service in the Tags text box.
   6. Click Add Item.

Create a web application

First, create a map on ArcGIS.com that contains your service and a basemap of the world. Next, use an application template from ArcGIS.com to create a web application.

Create a map on ArcGIS.com

Add your alumni_data service to a basemap on ArcGIS.com and save the map to use for your application.

Steps:

1. In the My Content section of ArcGIS.com, click Create Map.
2. Click Basemap and choose one of the basemaps.
3. Click Add > Add Layers.
4. Choose My Content from the In drop-down list.
5. Choose your alumni_data service and click Done Adding Layers.
6. Adjust the extent of your map, if necessary.
7. Save your map.
   1. Type a title, tags, and summary for the map.
   2. Choose in which folder to save the map.
   3. Click Save Map.
8. Share your map either publically or with specific groups.
9. Take note of the ID for your map; you will use this when creating a web application.

Use a template to create a web application

Since the application needs to allow editing, you will use the Edit web application template.

Steps:

1. Download the Edit web application template.
2. Place the downloaded ZIP file in the inetpub\wwwroot folder on your IIS server.
3. Extract the files.
4. Follow the instructions in the readme.html file to set up the application.