Programming with server objects

In this topic

ArcGIS Server objects

Once connected to the geographic information system (GIS) server, your application can use server objects running on the server and create objects within the server for use by the application. A server object is a coarse-grained ArcObjects component that runs in a process on the server object container (SOC) machine. ArcGIS Server comes with the following server objects:
The MapServer object provides access to the contents of a map document and methods for querying and drawing the map. The GeocodeServer object provides access to an address locator and methods for performing single address and batch geocoding. The GeodataServer object provides access to a geodatabase and methods for performing data management such as check out and synchronizing replicas. The GlobeServer object provides access to a globe document and methods for displaying the globe. These coarse-grained objects use the finer-grained ArcObjects on the server to perform their operations. Applications can use the high-level coarse-grained methods on the server object and can also drill down and work with the fine-grained ArcObjects associated with them (feature layers, feature classes, renderers, and so on).
A server object, unlike other ArcObjects components, can be preconfigured by a GIS server administrator. To preconfigure a server object, the GIS server administrator must set the object's properties using ArcCatalog or Manager before client applications can connect and use their functionality. When a server object is preconfigured, the administrator must specify a number of configuration properties, including the server object's pooling model. The pooling model dictates the type of usage that an application will make of the server object. This aspect of server object usage will be discussed in more detail later when the concept of stateful versus stateless use of the server is discussed.

Obtaining server objects from the server

You get a server object by asking the server for a server context containing the object. You can think of a server context as a process, managed by the server, within which a server object runs. Your application keeps a server object active by holding on to its context. The application releases the server object by releasing its context when it's finished with it. The following sample code shows how to obtain a GeocodeServer object from the GIS server and use it to locate an address.
[Java] 
IPropertySet addressProp = new IPropertySetProxy(m_context.createObject
    (PropertySet.getClsid()));
addressProp.setProperty("Street", street);
addressProp.setProperty("Zone", zone);
IPropertySet addressResults = m_geocodeServer.geocodeAddress(addressProp, null);
IFields results = new IFieldsProxy(m_context.createObject(Fields.getClsid()));
results = m_geocodeServer.getResultFields(addressResults);
String fieldName = null;
IPoint point = null;
for (int r = 0; r < results.getFieldCount(); r++){
    fieldName = results.getField(r).getName();
    if (fieldName.equals("Shape")){
        IGeometry geometry = new IGeometryProxy(addressResults. getProperty("Shape"))
            ;
        point = new IPointProxy(geometry);
        return point;
    }
}
A server object has other associated objects that a developer can get to and make use of—for example, a developer working with a MapServer object can get to the Map and Layer objects associated with that map. These are the same Map and Layer objects that an ArcGIS Desktop or ArcGIS Engine developer works with, except they reside in the server. The following sample code shows how to use the finer-grained ArcObjects associated with a MapServer object to work with a feature class associated with a particular layer.
[Java] 
IMapServerObjects mapServer = new IMapServerObjectsProxy(serverObject);

IMap map = mapServer.getMap("");
ILayer firstLayer = map.getLayer(0);
IFeatureLayer featureLayer = new IFeatureLayerProxy(firstLayer);
try{
    IFeatureClass featureClass = featureLayer.getFeatureClass();
    int count = featureClass.featureCount(null);
    System.out.println("Here is the count of features: " + count);
}

catch (ClassCastException cce){
    System.out.println("Sorry, the first layer in your Map was not a feature layer.")
        ;
}
In the previous code examples, pSOM is an IServerObjectManager interface that was retrieved from IGISServerConnection.ServerObjectManager. When the server object's work is done and the application is finished using objects associated with the server object (in the first case, pPoint; in the second case, pFeatureClass), the server context (pServerContext ) was explicitly released. The server context is released so other application sessions and other applications can use that server object. If your code does not explicitly release the context, it will be released once it goes out of scope and garbage collection occurs. However, there may be a considerable lag between when the server context variable goes out of scope and when garbage collection occurs, and if you rely on this mechanism, your server is controlled by the garbage collection in terms of when objects are released.
Garbage collection is the process by which the memory is reclaimed from objects that are created by applications. Garbage collection occurs based on memory allocations being made. When garbage collection occurs, objects that are not referenced are cleaned up, which may be some time after they go out of the scope of your application.

Obtaining a server object extension

Once you have a server object, you can get any extensions it supports and make method calls on them. A server object supports the IServerObjectExtensionManager interface, which has methods for getting all the extensions supported by the server object. These extensions can be out-of-the-box extensions installed with ArcGIS Server, or they can be custom extensions created by developers and registered with the GIS server.

Managing a server object's lifetime

A key aspect of using a server object is managing the server object’s lifetime. Server objects reside in server contexts, and you obtain a server object by calling CreateServerContext containing a specified server object.
The server object—for example, RedlandsGeocode, RedlandsMap—and all its associated objects are active and can be used as long as you hold on to the context. Once you release the server context (by calling ReleaseContext or allowing the context to go out of scope), you can no longer use the server object or any other objects you obtained from the context. Once a server object’s context is released, what happens to the context depends on whether or not the server object is pooled.
The following diagram illustrates the server object lifetime of a pooled server object in these steps:
  1. The client application makes a connection to the server object manager (SOM) and requests a server object.
  2. The SOM returns to the client a proxy to one of the server objects available in the pool.
  3. The client application works with the server object by making calls on its proxy.
  4. When the client is finished with the server object, it releases it. When the object is released, it is returned to the pool and is available to handle requests from other clients.
In the non-pooled case, when the context is released, it is shut down by the server. The next call to CreateServerContext for that server object creates a new instance of the server object in a new server context. If the server object is pooled, ReleaseContext returns the server object and its context to the pool, and the server is free to give the server object to a request from another application session. This aspect of server object and server context behavior is critical when designing your application and how it manages state.
The following diagram illustrates the server object lifetime of a non-pooled server object in thes steps:
  1. The client application makes a connection to the SOM and requests a server object.
  2. The SOM creates a new instance of the server object and returns to the client a proxy to the server object.
  3. The client application works with the server object by making calls on its proxy.
  4. When the client is finished with the server object, it releases it. When the object is released, it is destroyed. The SOM creates new instances of the server object to handle subsequent requests.