com.esri.arcgis.server
Interface IServerContext

All Superinterfaces:
Serializable
All Known Implementing Classes:
IServerContextProxy, ServerContext

public interface IServerContext
extends Serializable

Provides access to members for managing a server context, and the objects running within that server context.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Remarks

When developing applications with ArcGIS server, all ArcObjects that your application creates and uses live within a server context. A server context is a reserved space within the server dedicated to a set of running objects. GIS server objects also live 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 within the server to do add-hoc GIS processing.

All ArcObjects that your application uses should be created within a server context using the CreateObject method on IServerContext. Also, objects that are used together should be in the same context. For example, if you create a Point object to use in a spatial selection to query features in a feature class, the point should be in the same context as the feature class.

ArcGIS Server applications should not use New to create ArcObjects, but should always create objects by calling CreateObject on IServerContext.

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 unavailable to other applications until it is garbage collected. Once a context is released, the application can no longer make use of any objects in that context. This includes both objects that you may have obtained from the context or objects that you created in the context.

The IServerContext interface has a number of methods for helping you manage the objects you create within server contexts. The following is a description of how and when you would use these methods:

CreateObject

Use this method when you need to create an object for use in your application.

CreateObject will return a proxy to the object that is in the server context. Your application can make use of the proxy as if the object was created locally within its process. If you call a method on the proxy that hands back another object, that object will actually be in the server context and you application will be handed back a proxy to that object. In the above example, if you get a point from the point collection 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.

Also, you should 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.

For language specific examples (C#, Java, VB6, and VB.NET) illustrating the usage this method, view the detailed component help for CreateObject.

SetObject, GetObject

A context contains a dictionary that you can use as a convenient place to store objects that you create within the context. Note that this dictionary is itself valid only as long as you hold on to the server context and is emptied when you release the context. You can use this dictionary to share objects created within a context between different parts of your application that have access to the context.

SetObject adds objects to the dictionary, and GetObject  retrieves them. 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.

Remove, RemoveAll

Use these methods to remove object from a context that have been set using SetObject. Once an object is removed, a reference can no longer be made to it using GetObject. Note that if you do not explicitly call Remove or RemoveAll, you can still not get references to objects set in the context after the context has been released.

SaveObject, LoadObject

These methods allow you to serialize objects in the server context to strings, then deserialize them back into objects. Any object that supports IPersistStream can be saved and loaded using these methods. These methods allow you to copy objects between contexts. For example, if you use a GeocodeServer object to locate an address, then you want to draw the point that GeocodeAddress returns on your map, you need to copy the point into your MapServer's context.

Another important use of these methods is to manage state in your application while making statless use of pooled server object. A good example of this is in a mapping application. The initial session state for all users is the same and is equal to the map descriptor for the map server object. Each user can then change map descriptor properties such as the extent and layer visibility, which need to be maintained in the users session state. The application does this by saving a serialized map descriptor as part of each users session state. Using the serialized string representation allows the application to take advantage of the standard session state management facilities of the web server. The application uses the LoadObject and SaveObject methods to reconstitute the sessions map descriptor whenever it needs to make edits to it in response to user changes or whenever it needs to pass the map descriptor to the map server object for drawing the map according to the users specifications.

It's important to note that if you are building a web application using the ESRI web controls, the WebMap object takes care of saving and loading the MapDescription for you.

See Also:
IGISServerConnection, IServerObjectAdmin, ServerConnection, IServerContext, IServerObject, IMapServer

Method Summary
 Object createObject(String cLSID)
          Create an object in the server context whose type is specified by the CLSID.
 Object getObject(String name)
          Get a reference to an object in the server context's object dictionary by its Name.
 IServerObject getServerObject()
          The map or geocode server object running in the server context.
 Object loadObject(String str)
          Create an object in the server context from a string that was created by saving an object using SaveObject.
 void releaseContext()
          Release the server context back to the server so it can be used by another client (if pooled), or so it can be destroyed (if non-pooled).
 void remove(String name)
          Remove an object from the server context's object dictionary.
 void removeAll()
          Remove all objects from the server context's object dictionary.
 String saveObject(Object obj)
          Save an object in the server context to a string.
 void setObject(String name, Object obj)
          Add an object running in the server context to the context's object dictionary.
 

Method Detail

getServerObject

public IServerObject getServerObject()
                              throws IOException,
                                     AutomationException
The map or geocode server object running in the server context.

Supported Platforms

Windows, Solaris, Linux

Remarks

The ServerObject property of a server context returns the server object that is running withing the server context. If you use the CreateServerContext method on IServerObjectManager to create a a server context based on a server object configuration, use the ServerObjectProperty to get a reference to the server object that is running within that context.

Returns:
An reference to a com.esri.arcgis.server.IServerObject
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

createObject

public Object createObject(String cLSID)
                    throws IOException,
                           AutomationException
Create an object in the server context whose type is specified by the CLSID.

Supported Platforms

Windows, Solaris, Linux

Remarks

Use this method when you need to create an object for use in your application.

Create object will return a proxy to the object that is in the server context. Your application can make use of the proxy as if the object was created locally within its process. If you call a method on the proxy that hands back another object, that object will actually be in the server context and you 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.

Also, you should 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:

IPointSet remotePoint = new Point(svrContext.createObject(Point.getClsid()));

while objects with Local in their name are objects are objects created locally as in:

IPointSet localPoint = new Point();  

You canít set a local object to a remote object:

// this is incorrectlocalPoint = remotePoint;// this is also incorrectlocalElement.setGeometry(remotePoint);

Do not set a local object, or a property of a local object, to be an object obtained from a remote object:

// this is incorrectlocalPoint = remotePointCollection.getPoint(0);

When calling a method on a remote object, donít pass in local object as parameters:

// this is incorrectremoteWksp = remoteWkspFactory.open(localPropSet, 0);

You can get simple data types (double, long, string, etc) that are passed by value from a remote object and use them as properties of a local object as in:

// this is oklocalPoint.setX(remotePoint.getX());localPoint.setY(remotePoint.getY());

Example

IPointCollection pointColl = new IPointCollectionProxy(serverContext.createObject(Polygon.getClsid()));

Parameters:
cLSID - The cLSID (in)
Returns:
A reference to another Object (IUnknown)
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

loadObject

public Object loadObject(String str)
                  throws IOException,
                         AutomationException
Create an object in the server context from a string that was created by saving an object using SaveObject.

Supported Platforms

Windows, Solaris, Linux

Remarks

These methods allow you to serialize objects in the server context to strings, then deserialize them back into objects. Any object that supports IPersistStream can be saved and loaded using these methods. These methods allow you to copy objects between contexts. For example, if you use a GeocodeServer object to locate an address, then you want to draw the point that GeocodeAddress returns on your map, you need to copy the point into your MapServer's context.

Another important use of these methods is to manage state in your application while making statless use of pooled server object. A good example of this is in a mapping application. The initial session state for all users is the same and is equal to the map descriptor for the map server object. Each user can then change map descriptor properties such as the extent and layer visibility, which need to be maintained in the users session state.  The application does this by saving a serialized map descriptor as part of each users session state. Using the serialized string representation allows the application to take advantage of the standard session state management facilities of the web server. The application uses the LoadObject and SaveObject methods to reconstitute the sessions map descriptor whenever it needs to make edits to it in response to user changes or whenever it needs to pass the map descriptor to the map server object for drawing the map according to the users specifications.

It's important to note that if you are building a web application using the ESRI web controls, the WebMap object takes care of saving and loading the MapDescription for you.

Example

IServerContext serverContext1 = serverObjectManager.createServerContext("RedlandsMap","MapServer");IServerContext serverContext2 = serverObjectManager.createServerContext("RedlandsGeocode","GeocodeServer");IPoint point = new IPointProxy(serverContext2.createObject(Point.getClsid()));point.setX(1.0);point.setY(1.0);String strPoint = serverContext2.saveObject(point);IPoint pointCopy = new IPointProxy(serverContext1.loadObject(strPoint));

Parameters:
str - The str (in)
Returns:
A reference to another Object (IUnknown)
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

saveObject

public String saveObject(Object obj)
                  throws IOException,
                         AutomationException
Save an object in the server context to a string.

Supported Platforms

Windows, Solaris, Linux

Remarks

These methods allow you to serialize objects in the server context to strings, then deserialize them back into objects. Any object that supports IPersistStream can be saved and loaded using these methods. These methods allow you to copy objects between contexts. For example, if you use a GeocodeServer object to locate an address, then you want to draw the point that GeocodeAddress returns on your map, you need to copy the point into your MapServer's context.

Another important use of these methods is to manage state in your application while making statless use of pooled server object. A good example of this is in a mapping application. The initial session state for all users is the same and is equal to the map descriptor for the map server object. Each user can then change map descriptor properties such as the extent and layer visibility, which need to be maintained in the users session state.  The application does this by saving a serialized map descriptor as part of each users session state. Using the serialized string representation allows the application to take advantage of the standard session state management facilities of the web server. The application uses the LoadObject and SaveObject methods to reconstitute the sessions map descriptor whenever it needs to make edits to it in response to user changes or whenever it needs to pass the map descriptor to the map server object for drawing the map according to the users specifications.

It's important to note that if you are building a web application using the ESRI web controls, the WebMap object takes care of saving and loading the MapDescription for you.

Example

IServerContext serverContext1 = serverObjectManager.createServerContext("RedlandsMap","MapServer");IServerContext serverContext2 = serverObjectManager.createServerContext("RedlandsGeocode","GeocodeServer");IPoint point = new IPointProxy(serverContext2.createObject(Point.getClsid()));point.setX(1.0);point.setY(1.0);String strPoint = serverContext2.saveObject(point);IPoint pointCopy = new IPointProxy(serverContext1.loadObject(strPoint));

Parameters:
obj - A reference to another Object (IUnknown) (in)
Returns:
The str
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getObject

public Object getObject(String name)
                 throws IOException,
                        AutomationException
Get a reference to an object in the server context's object dictionary by its Name.

Supported Platforms

Windows, Solaris, Linux

Remarks

A context contains a dictionary that you can use as a convenient place to store objects that you create within the context. Note that this dictionary is itself valid only as long as you hold on to the server context and is emptied when you release the context. You can use this dictionary to share objects created within a context between different parts of your application that have access to the context.

SetObject adds objects to the dictionary, and GetObject  retrieves them. 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.

Parameters:
name - The name (in)
Returns:
A reference to another Object (IUnknown)
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

setObject

public void setObject(String name,
                      Object obj)
               throws IOException,
                      AutomationException
Add an object running in the server context to the context's object dictionary.

Parameters:
name - The name (in)
obj - A reference to another Object (IUnknown) (in)
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

remove

public void remove(String name)
            throws IOException,
                   AutomationException
Remove an object from the server context's object dictionary.

Supported Platforms

Windows, Solaris, Linux

Remarks

Remove and RemoveAll to remove object from a context that have been set using SetObject. Once an object it can no longer be retrieved using GetObject. Note that if you do not explicitly call Remove or RemoveAll, you can still not get references to objects set in the context after the context has been released.

Example

serverContext.remove("myPoly");

Parameters:
name - The name (in)
Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

removeAll

public void removeAll()
               throws IOException,
                      AutomationException
Remove all objects from the server context's object dictionary.

Supported Platforms

Windows, Solaris, Linux

Remarks

Remove and RemoveAll to remove object from a context that have been set using SetObject. Once an object is removed, a reference can no longer be made to it using GetObject. Note that if you do not explicitly call Remove or RemoveAll, you can still not get references to objects set in the context after the context has been released.

Example

serverContext.remove("myPoly");

Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

releaseContext

public void releaseContext()
                    throws IOException,
                           AutomationException
Release the server context back to the server so it can be used by another client (if pooled), or so it can be destroyed (if non-pooled).

Supported Platforms

Windows, Solaris, Linux

Remarks

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 unavailable to other applications until it is garbage collected. Once a context is released, the application can no longer make use of any objects in that context. This includes both objects that you may have obtained from the context or objects that you created in the context.

Example

IServerContext serverContext = serverObjectManager.createServerContext("RedlandsMap","MapServer");IMapServer server = new IMapServerProxy(serverContext.getServerObject());// Do something with the objectserverContext.releaseContext();

Throws:
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.