Local (DCOM) connections are only supported for ArcGIS Server versions prior to 10.1.
Local and Internet connections
ArcGIS for Server services can be made accessible via local and Internet connections. Local connections are established by using ArcObjects in a client application to connect to the Server Object Manager (SOM). Internet connections are established by using native objects in a client application to connect to a Web service endpoint. "Native object" means an object managed solely in the native development environment, such as .NET or Java. Local connections work with services—namely server objects and server context—using the ArcObjects application programming interface (API) and the Simple Object Access Protocol (SOAP) API. Stateful changes to a service (server object) can only be made using the ArcObjects API and require a local connection. Internet connections only work with services using the SOAP API, so all service interaction is stateless. In general, ArcGIS for Server connections in client applications can be summarized as follows:
- Internet connections always use the SOAP API and define a connection using a uniform resource locator (URL) to a Web service endpoint. Internet connections can be used by both internal (local area network [LAN]) and external (Internet) clients.
- Local connections always use the ArcObjects API and can use the SOAP API, depending on the client application. Connections are defined using the name of the SOM machine with optional identity credentials. Local connections can only be used by internal (LAN) clients.
The two connection types are shown in the following diagram:
Both connection types can be used to consume ArcGIS Server services in pre-created application clients such as ArcMap, ArcCatalog, and ArcGIS Explorer. The Web Application Developer Framework (ADF) and ArcGIS Server Manager (Manager) also enable the use of ArcGIS Server services without explicitly defining the API you're using. The API becomes important for application developers to determine the capabilities and limits when working with ArcGIS Server services. Working with the SOAP API requires developer-level skill and knowledge for a number of Web service standards and specifications, in addition to ArcGIS Server service capabilities.
Web service standards
The ArcGIS for Server SOAP API supports two standard Extensible Markup Language (XML)-based specifications: Web Service Description Language (WSDL) and SOAP. WSDL is a specification used to describe networked XML-based services. Although the term "Web Service" is part of the moniker, WSDL is not restricted to traditional Hypertext Transfer Protocol (HTTP)-based Web services. In general, WSDL provides a simple way for service providers to describe the basic format of requests to their services, regardless of the underlying protocol. One of those protocols, and the most popular, is SOAP. SOAP is used to describe the format of a message sent to a networked service. SOAP messages can be transmitted to a service via a number of transport protocols, including HTTP and Distributed Component Object Model (DCOM).
For more information on WSDL and SOAP, see the WSDL documentation and the SOAP documentation on the World Wide Web Consortium Web site.
ArcObjects server object and extension types
SOAP support for server objects and server object extensions is defined at the ArcObjects level. At some point in the communication cycle, ArcObjects must be used. Two basic ArcObjects interfaces are used to interact with the SOAP API: IServiceCatalogAdmin and IRequestHandler. Updated versions of both interfaces are available (for example, IServiceCatalogAdmin2 and IRequestHandler2). IServiceCatalogAdmin is used to get a WSDL for server objects, server object extensions, and ServiceCatalog. ServiceCatalog is a well-known service managed internally by the SOM and used to get a list of services and their properties from an ArcGIS Server site using the SOAP API. IRequestHandler is used to process SOAP requests and generate SOAP responses. Interaction with an ArcGIS Server service via the SOAP API supports the implementation and use of the IRequestHandler interface. The following table lists ArcGIS Server services and extensions that provide a WSDL and implement the IRequestHandler interface, so they can be used via the SOAP API:
|
Service type
|
ArcObjects server object or extension type
|
|
Map Service
|
MapServer
|
|
Geocode Service
|
GeocodeServer
|
|
Geodata Service
|
GeoDataServer
|
|
Geoprocessing Service
|
GPServer
|
|
Globe Service
|
GlobeServer
|
|
Network Analysis
|
NAServer
|
WSDLs
The SOM provides the WSDL for a service type to a client. The WSDL for each supported service type is stored in the <ArcGIS Install>\XMLSchema folder using the server type name with the file extension ".wsdl".
You can access the WSDL for each service type by using the ArcObjects API and the IServiceCatalogAdmin interface on the ServiceCatalog object. The ServiceCatalog (Catalog) WSDL is returned by the GetCatalogDescriptionDocument() method and each service type (for example, MapServer or GeocodeServer) WSDL is returned by the GetDescriptionDocument() method. The byte array returned from either method contains the WSDL document referenced in the WSDL and SOAP documentation links previously mentioned. The IServiceCatalogAdmin interface is included in ESRI.ArcGIS.Server.dll. See the following code:
[C#]
ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection gisconnection = new
ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection();
gisconnection.Host = servername;
gisconnection.Connect();
IServerObjectManager serverManager = gisconnection.ServerObjectManager;
IServerContext serverContext = serverManager.CreateServerContext(servicename,
servertype);
IServiceCatalogAdmin2 isc = (IServiceCatalogAdmin2)serverContext.CreateObject(
"esriServer.ServiceCatalog");
UTF8Encoding utf8 = new UTF8Encoding();
// Catalog WSDL:
byte[] bitscatalog = isc.GetCatalogDescriptionDocument("Catalog", "http://localhost")
;
string catalog_wsdl = utf8.GetString(bitscatalog);
// Service WSDL:
byte[] bitsservice = isc.GetDescriptionDocument(servicename, servertype,
"http://localhost");
string service_wsdl = utf8.GetString(bitsservice);
Requests and responses
SOAP requests to ArcGIS Server services are handled by the server object via the implementation of the IRequestHandler interface. Using the ArcObjects API, a client to ArcGIS Server can use the IRequestHandler interface to submit a SOAP request and return a SOAP response. The IRequestHandler interface defines the HandleStringRequest method to process SOAP string requests and generate SOAP string responses.
The following code example shows how to query the IRequestHandler interface from a MapServer object, create the SOAP string request to get the default map name, and submit the request with a capability list to return a SOAP string response. The IRequestHandler interface is included in ESRI.ArcGIS.System.dll and referenced via the ESRI.ArcGIS.esriSystem namespace.
[C#]
IRequestHandler irh = (IRequestHandler)serverContext.ServerObject;
string soap_request = "<?xml version='1.0' encoding='utf-8' ?>";
soap_request +=
"<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' xmlns:tns='http://www.esri.com/schemas/ArcGIS/9.2'>";
soap_request += "<soap:Body>";
soap_request += "<tns:GetDefaultMapName>";
soap_request += "</tns:GetDefaultMapName>";
soap_request += "</soap:Body>";
soap_request += "</soap:Envelope>";
string soap_response = irh.HandleStringRequest("map,query,data", soap_request);
Creating and parsing SOAP strings can be a labor intensive process. Using the raw WSDL to determine how to create SOAP requests and process SOAP responses can be a daunting task. Esri has leveraged existing technology standards coupled with developer environment utilities to make this process easier.