Working with server contexts

---

If you want your application to go beyond simple mapping and geocoding using server objects and Web controls, you must become familiar with working with server contexts as well as the ArcObjects programming model.

The ServerContext object provides access to a context in the geographic information system (GIS) server and to methods for creating and managing objects within that context. The ServerContext object is shown in the following illustration.

The ServerObjectManager object provides methods for obtaining information about the GIS server and for creating server contexts for use by an application. The ServerObjectManager object is shown in the following illustration.

You get a server context using the CreateServerContext method on IServerObjectManager, which hands back an IServerContext interface on the server context. The IServerContext interface has a number of methods for helping you manage the objects you create in server contexts. 

The IServerObjectManager interface and its methods are shown in the following table.

The IServerContext interface and its methods are shown in the following table.

When developing applications with ArcGIS Server, all ArcObjects that your application creates and uses reside in a server context. A server context is a reserved space on the server dedicated to a set of running objects. Server objects also reside in a server context. To get a server object, you actually get a reference to its context, then get the server object from the context. You can also create empty server contexts. You can use an empty context to create ArcObjects on the fly in the server to perform ad hoc GIS processing.

An empty server context is useful when you want to create objects for your application's use in the server but do not require a preconfigured server object. Empty contexts can be used to create any type of object, such as a connection to a workspace. Since server objects are ArcObjects, you can also use empty contexts to create server objects (MapServer, GeocodeServer, GeodataServer, GlobeServer) on the fly. Empty server contexts are non-pooled and have high isolation.

When your application is finished working with a server context, it must release it back to the server by calling the ReleaseContext method. If you allow the context to go out of scope without explicitly releasing it, it will remain in use and be unavailable to other applications until it is garbage collected. Once a context is released, the application can no longer use any objects in that context. This includes objects that you may have obtained from, or created in, the context.

CreateObject will return a proxy to the object that is in the server context. Your application can use the proxy as if the object was created locally in its process. If you call a method on the proxy that hands back another object, that object will be in the server context and your application will be handed back a proxy to that object. For example, if you get a point from a point collection in the server context using IPointCollection.Point(), the point returned will be in the same context as the point collection.

If you add a point to the point collection using IPointCollection.AddPoint(), the point should be in the same context as the point collection.

Do not directly use objects in a server context with local objects in your application and vice-versa. You can indirectly use objects, or make copies of them. For example, if you have a Point object in a server context, you can get its X,Y properties and use them with local objects, or use them to create a new local point. Don’t directly use the point in the server context as, for example, the geometry of a local graphic element object.

Consider the following examples. In each example, assume that objects with Remote in their names are objects in a server context as in the following:

IPointSet remotePoint = new Point(svrContext.createObject(Point.getClsid()));while objects with Local in their name are objects created locally as shown in the following code.

IPointSet localPoint = new Point();

You can’t set a local object to a remote object as shown in the following code.

// The following is incorrect:
localPoint = remotePoint;
// The following is also incorrect:
localElement.setGeometry(remotePoint);

Do not set a local object, or a property of a local object, to be an object obtained from a remote object as shown in the following code.

// The following is incorrect:
localPoint = remotePointCollection.getPoint(0);

When calling a method on a remote object, don’t pass in local objects as parameters as shown in the following code.

// The following is incorrect:
remoteWksp = remoteWkspFactory.open(localPropSet, 0);

You can get simple data types (double, long, string, and so on) that are passed by value from a remote object and use them as properties of a local object as shown in the following code.

// The following is correct:
localPoint.setX(remotePoint.getX());
localPoint.setY(remotePoint.getY());

As your application creates and uses various objects in a particular context, you may want a convenient place to store references to commonly used objects within the context. You can do this by using the server context's object dictionary to keep track of these objects during the lifetime of the context. You can use the context's dictionary as a convenient place to store objects that you create in the context. This dictionary is valid only as long as you hold on to the server context, and it's emptied when you release the context. You can use this dictionary to share objects created in a context between different parts of your application that have access to the context.

For example, your application can make repeated use of a geometry object across requests. Rather than creating the geometry object over and over again, your application can store the geometry object in the context's dictionary so you can use it multiple times without recreating it. This is shown in the following code.

You add objects to and retrieve objects from the dictionary using the SetObject and GetObject methods, respectively. An object that is set in the context will be available until it is removed (by calling Remove or RemoveAll) or until the context is released.

IPolygonSet remotePoly = new Polygon(svrContext.createObject(Polygon.getClsid()));
IPolygonSet localPoly = new Polygon();

Use the Remove and RemoveAll methods to remove an object from a context that has been set using SetObject as shown in the following code. Once an object is removed, a reference to it can no longer be obtained using GetObject. If you do not explicitly call Remove or RemoveAll, you can not get references to objects set in the context after the context has been released.

remove("localPoly");

A server context contains an object dictionary that serves as a convenient place for you to store references to commonly used objects as illustrated in the following graphic. Use the SetObject and GetObject methods on IServerContext to work with the object dictionary.

When your application performs operations using ArcObjects running in server contexts, those operations may need to write out data to disk. For example, the ExportMapImage method on a map server object writes images to disk and the CheckOut method on a geodata server object writes personal geodatabases to disk. You may have other applications that need to write data; for example, an application that uses geoprocessing objects to create shapefiles needs to write those shapefiles to a disk from which they can be downloaded. Typically, you will want these files to be cleaned up by the server after some period of time. To ensure this happens, your applications should write their output to a server directory.

The set of a GIS server’s server directories is available by calling GetServerDirectoryInfos on the IServerObjectManager interface on the server object manager (SOM). For your files to be cleaned up when written into that server directory, they must follow a file naming convention. The GIS server will delete all files in a server directory that are prefixed with "_ags_". Any files written to an output directory that are not prefixed with "_ags_" will not be cleaned by the GIS server.

The IServerDirectoryInfo interface and its methods are shown in the following table.

If your server object container (SOC) machines have licenses for the Spatial, 3D, Network, or Data Interoperability extensions for ArcGIS Server, your applications can use the functionality that is unlocked by that license.

You do not need to perform an explicit call to get a license when you want to use an object that requires a license. Just create the object on the server and use it. If the SOC machine is not licensed, then any method calls you make on the object will fail.