I had written about ESRI’s Java Web ADF a long time back when I first started this blog. In that entry, the description was pretty much a rehash of the material from ESRI’s web site. Since then I have had some more experience with this API and after months and months of procrastination I finally took it upon myself to write it up.
I must add this caveat though: what I will write here is my understanding of the system and not based on the excellent (sarcasm intended) documentation that you generally get from Java Web ADF resource center. So, as is always the case in these situations, feedback is essential (and definitely well appreciated).
Let me start with a graphic:
[
As usual this graphic was created using Steve Hanov's online drawing tool and edited using the Pixlr online photo editor.]
I agree the graphic is not very professional and actually pretty cartoonish but I think it is good enough to give a mental picture of the discussion that follows.
On the right end of the above graphic, we can see the ArcGIS server. Although it might seem from the graphic that the SOC is the only component of the ArcGIS server, it is not entirely true. Another component of the server ecosystem is the SOM. I have simplified the diagram a bit and have not shown the SOM or the physical machine(s) that host those components. These facts are not relevant to this discussion.
The goal of any application that integrates ESRI’s ArcGIS Server is to offload geospatial computation to the server side. (Just to be clear, in this discussion the web application (normally hosted by a web application container like Tomcat) is the “client” that requests geospatial computations to the ArcGIS Server that is the “server”. In this discussion we are not going to talk about the DHTLM-JavaScript-CSS based user interface client that resides on a (human) user’s browser.) These geospatial computations are encapsulated by combinations of various ArcObjects.
Since the web application resides in a different process space than the ArcGIS Server (be it on the same machine or on a different machine as shown in the above graphic) how can we get hold of the ArcObjects? Well, ESRI exposes ArcObjects using Microsoft’s DCOM technology. So if you are familiar with DCOM programming (which I am not, so I am not going to dwell on it too much) then you get hold of the DCOM-based ArcObject proxies and invoke the relevant methods directly.
In my case, my web application is a Java based one. One way to make the Java code to invoke methods on ArcGIS hosted ArcObjects is by the use of SOAP. A method invocation is encapsulated in a SOAP message and then transmitted down the wire to the ArcGIS Server which converts the SOAP message to a call on an ArcObject and finally sends the response back to the caller, again using SOAP. We could easily have used DCOM’s in-built serialization protocol if that is supported in Java.
The ADF is made up of 2 primary packages: com.esri.adf.web.data and com.esri.adf.web.faces. The latter package is focused more on the front-end components that make up the web application and is not really the topic of discussion here. The former package can be thought of as containing all the “domain” objects that make up a geospatial application. These domain objects are quite intelligent in the sense that they are aware of where to get data and computation services from and how to manage their own lifecycles. These “intelligent domain” objects come preprogrammed with servicing the most standard geospatial computations. Essentially, these objects are preprogrammed with all the logic necessary to invoke SOAP requests to the ArcGIS Server and marshall and unmarshall data.
In the typical development scenario, the geospatial part of the web application consists of a combination of one or more objects from the com.esri.adf.web.data package. Classes like WebContext, WebMap, WebToc, WebQuery etc all have preprogrammed logic that knows how to interact with the ArcGIS Server to service standard operations like panning a map, zooming in and out, spatial queries etc.
Sometimes, the typical usage may not be enough. During that time one might want to manipulate the ArcObject proxies directly. These come in the package com.esri.arcgisws. Just to be clear, my guess is that the objects in the com.esri.adf.web.data package use the proxies in the com.esri.arcgisws package.
Hopefully the explanation above will help one understand how all the different packages are weaved together in the ESRI Java Web ADF ecosystem.
Powered by ScribeFire.
Every time I create a new Java Web ADF application a lot of JAR files get added in the WEB-INF/lib directory. It is quite obvious that not all of these libraries are needed for the project and I always wanted to clean that part up. Finally I got a chance and found out that the following JAR files are not needed if you are writing an application that uses an ArcGIS server as the data source:
- arcgis_webcontrols_wms
- axis-schema
- arcgis_ejb_stubs
- arcgis_jcs
- arcgis_webcontrols_arcweb
- arcgis_webcontrols_ejb
- arcgis_webcontrols_arcims
- axis-ant
- mlibwrapper_jai
- arcgis_arcweb_stubs
- arcims_jconnect
Our application utilizes most of the mapping capabilities but does not include any sort of editing. I do not know yet if some of the above JAR files will be needed if we include such capabilities.
The com.esri.adf.web.data.GISResource interface provides access to a proxy preconfigured with the connection details of a service on the SOM. The interface also provides access to the functionalities that are applicable for that resource.
GISResource instances are defined as managed beans in the faces-config.xml. The resources are then tied up with the WebContext of the application.
One example of a GISResource implementation is the AGSMapResource.This resource provides a proxy called MapServerPort that proxies the mapping service on the SOM. Behind the scenes the service on the SOM interacts with the MapServer ArcObject on the SOC. Hence, using the MapServerPort one can send specific commands to the ArcObjects back-end (through the service on the SOM), commands that are applicable to a map. Some examples are querying map data, manipulation of map image etc.
Another example of a GISResource implementation is the AGSGeocodeResource. This resource provides a proxy called GeocodeServerPort that proxies the GeocodeServer ArcObject on the SOC.
Example of a GISResource instance declared as a managed bean:
<managed-bean> <managed-bean-name>agsws0</managed-bean-name> <managed-bean-class> com.esri.adf.web.ags.data.AGSMapResource </managed-bean-class> <managed-bean-scope>none</managed-bean-scope> <managed-property> <property-name>endPointURL</property-name> <value> http:/ip:port/arcgis/services/serviceGroup/serviceName/MapServer </value> </managed-property> <managed-property> <property-name>user</property-name> <value>#{agswsUser1}</value> </managed-property> <managed-property> <property-name>alias</property-name> <value>Some Alias</value> </managed-property> <managed-property> <property-name>functionalities</property-name> <map-entries> <map-entry> <key>map</key> <value>#{agsMap}</value> </map-entry> <map-entry> <key>tile</key> <value>#{agsTile}</value> </map-entry> <map-entry> <key>toc</key> <value>#{agsToc}</value> </map-entry> <map-entry> <key>query</key> <value>#{agsQuery}</value> </map-entry> </map-entries> </managed-property> </managed-bean>
(Anything above in #{} are defined elsewhere and is not shown here.)
Example of the above map resource being tied up to the WebContext:
<managed-bean>
<managed-bean-name>mapContext</managed-bean-name>
<managed-bean-class>
com.esri.adf.web.data.WebContext
</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
<managed-property>
<property-name>webSession</property-name>
<value>#{esriWebSession}</value>
</managed-property>
<managed-property>
<property-name>attributes</property-name>
<map-entries>
<map-entry>
<key>map</key>
<value>#{map}</value>
</map-entry>
<map-entry>
<key>overview</key>
<value>#{overview}</value>
</map-entry>
<map-entry>
<key>toc</key>
<value>#{toc}</value>
</map-entry>
<map-entry>
<key>graphics</key>
<value>#{graphics}</value>
</map-entry>
<map-entry>
<key>query</key>
<value>#{query}</value>
</map-entry>
<map-entry>
<key>history</key>
<value>#{extentHistory}</value>
</map-entry>
<map-entry>
<key>geocode</key>
<value>#{geocode}</value>
</map-entry>
<map-entry>
<key>results</key>
<value>#{results}</value>
</map-entry>
<map-entry>
<key>scaleBar</key>
<value>#{scaleBar}</value>
</map-entry>
</map-entries>
</managed-property>
<managed-property>
<property-name>resources</property-name>
<map-entries>
<map-entry>
<key>agsws0</key>
<value>#{agsws0}</value>
</map-entry>
</map-entries>
</managed-property>
</managed-bean>
(Again, anything above in #{} are defined elsewhere and is not shown here.)
Example Java code that retrieves the resource:
WebContext webContext = webMap.getWebContext();
Map resources = webContext.getResources();
AGSMapResource agsMapResource = (AGSMapResource) resources.get(”agswso”);
Example Java code that sends a query to the back-end ArcObject:
URL url = agsMapResource.getEndPointURL();
MapServerBindingStub mapserver = new MapServerBindingStub(new URL(url), null);
MapServerInfo mapinfo = mapserver.getServerInfo(mapserver.getDefaultMapName());
MapDescription mapdesc = mapinfo.getDefaultMapDescription();
RecordSet recordSet = mapserver.queryFeatureData(mapdesc.getName(), layerId, query);
In the above the layerId variable is an int that specifies which specific layer needs to be queried and query is an instance of a QueryFilter that specifies the details of the query that is to be run.
The Java Web ADF, part of the ArcGIS Server ADF, is a library of objects that assist in the development of GIS web applications. The library consists of a bunch of objects which are organized in a MVC framework. The web controls define standard interactions with maps and also provide hook ups to backend ArcObjects. ESRI decided to build the Web ADF based on JSF and hence a knowledge of JSF is necessary for developing applications using the Java Web ADF. The Java Web ADF is made up primarily of 3 groups of objects:
- View: Objects in this layer consist of preprogrammed visual controls. These are JSF components that can be plugged into a JSP using JSF tags. The backing beans behind these controls serve as controllers too.
- Model 1: Objects in this layer are beans that provide the data layer for the objects in the view layer. The data objects provide support for the data on the web. These objects also act as a business logic layer for certain standard GIS functionality. Such functionality is provided by interacting with the server (ArcGIS server) objects.
- Model 2: Objects in this layer complement the objects in the Model 1 layer by providing purely GIS data and functionality. The objects in this layer are provided with intelligence of how to pull data from appropriate resources.
The view objects deal with presentation and user interaction. To deal with user interactions, the Java Web ADF contains the following categories of objects:
- Commands: These require a 1-step interaction from users. On the web page, once the user clicks on a button or some other control something happens on the server side. The server acts on information available at the time of the clicking. Examples can be “Zoom to full extent”, “Information at current point” etc. Implementation-wise, such constructs are implemented as JSF actions or action listeners depending on whether the interaction results in a navigation change or not.
- Tools: These require at least a 2-step interaction from users. This means that the interaction is initiated by the user clicking a control and then continues the interaction by performing some more actions. An example can be “Zoom to rectangle” which is initiated by the user clicking on a Zoom In or Zoom Out button and then continuing by setting a rectangle. After the user interaction is completed a request is sent back to the server side where a server side component handles the request.
- Tasks: While commands and tools handle the more traditional and more visual of the map controls, tasks (and the associated task framework) are supposed to handle the more non-traditional interactions with geospatial data. The result of running these tasks are generally result sets but these results can impact the visual aspects also. Examples can be customized queries that result in the highlighting of features (from the result) in the map.
Briefly, ArcGIS Server is a collection of server-side components (ArcObjects) providing GIS functionality and a mechanism to interact with these ArcObjects. ArcGIS Server is organized in a system of servers.
The system of servers hosting the ArcObjects consist of a Server Object Manager (SOM) and one or more Server Object Containers (SOC). The SOCs contain the actual ArcObjects and perform the computations while the SOM acts as a gateway to the SOCs and performs most of the component management tasks. A client application interacts only with the SOM. In most cases, therefore, the SOM and ArcObjects can be used interchangeably.
ESRI provides APIs, called ArcGIS Server ADF, written in various languages that allows developers to interact with the SOM. These APIs contain web controls and proxies to the back-end ArcObjects. The proxies abstract out all the communication between the client application (the developers write) and the SOM. In the 9.2 version of the software, the communication between the client application and the SOM is through SOAP over HTTP.
Important URLs:
http://edndoc.esri.com/arcobjects/9.2/NET_Server_Doc/developer/ArcGIS/SOAP/overview.htm
I am currently working with ESRI’s ArcGIS Server 9.2/9.3 (Java edition). This software is fairly new to me and so I decided to collect bits and pieces of information about the software itself and how to program with it. As other people working with this software will verify, documentation on this software is, in short, “lacking”. I am not trying to override the official documentation that ESRI provides, I am merely trying to organize my thoughts about this software. This might come in handy for my current team members, other people working with this software or even to myself a few years down the road!
Specifically, I am trying to target the following topics for now:
- General architecture of the ArcGIS Server (primarily 9.2, currently evaluating the new REST style architecture of 9.3 so that might be covered also).
- Java Web ADF (9.2).
- Flex API (9.3).
- JavaScript API (this is optional for me right now).
Code samples may or may not be present. I will try to provide some.
Comments are welcome. I understand that I am fairly new to this and so I may not be “getting it correct” all the time. Part of the reason for writing this blog is to make sure that my understanding is consistent with others experienced with this software.