com.esri.arcgis.server
Class ServerContext

java.lang.Object
  extended bycom.esri.arcgis.server.ServerContext
All Implemented Interfaces:
IServerContext, Serializable

public class ServerContext
extends Object
implements IServerContext

The ServerContext object used for working with ArcObjects in the GIS server.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Remarks

A ServerContext is a reserved space within the server dedicated to a set of running objects. GIS server objects also live in a server context. When developing applications with ArcGIS server, all ArcObjects that your application creates and uses live within a server context.

This object supports a single interface: IServerContext. You can get at the server object running within a server context using the ServerObject property on IServerContext. IServerContext also contains methods for creating and managing objects running within the ServerContext.

You get a ServerContext by calling the CreateServerContext method on IServerObjectManager.

See Also:
Serialized Form

Constructor Summary
ServerContext(Object obj)
          Construct a ServerContext using a reference to such an object returned from a COM server
 
Method Summary
static ServerContext bindUsingMoniker(String moniker)
          Bind to a running instance of this class using the supplied ObjRef moniker
 Object createObject(String cLSID)
          Create an object in the server context whose type is specified by the CLSID.
 boolean equals(Object o)
          Compare this object with another
static ServerContext getActiveObject()
          Get a reference to a running instance of this class on the current machine using native code.
 IServerContext getAsIServerContext()
          Access this class's com.esri.arcgis.server.IServerContext interface
 Object getObject(String name)
          Get a reference to an object in the server context's object dictionary by its Name.
 Object getPropertyByName(String name)
          Get the value of a property dynamically at run-time, based on its name
 Object getPropertyByName(String name, Object rhs)
          Get the value of a property dynamically at run-time, based on its name and a parameter
 IServerObject getServerObject()
          The map or geocode server object running in the server context.
 int hashCode()
          the hashcode for this object
 Object invokeMethodByName(String name)
           
 Object invokeMethodByName(String name, Object[] parameters)
          Invoke a method dynamically at run-time to pass primitive types (eg Integer to pass an int).
 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.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ServerContext

public ServerContext(Object obj)
              throws IOException
Construct a ServerContext using a reference to such an object returned from a COM server

Parameters:
obj - an object returned from a COM server
Throws:
IOException - if there are problems communicating via DCOM
Method Detail

getAsIServerContext

public IServerContext getAsIServerContext()
Access this class's com.esri.arcgis.server.IServerContext interface


equals

public boolean equals(Object o)
Compare this object with another


hashCode

public int hashCode()
the hashcode for this object


getActiveObject

public static ServerContext getActiveObject()
                                     throws AutomationException,
                                            IOException
Get a reference to a running instance of this class on the current machine using native code. Uses native code (See GetActiveObject() in MS doc) and thus can only be used on MS Windows

Returns:
A reference to the running object.
Throws:
IOException - If there are communications problems.
AutomationException - If there was an error attaching to the instance.

bindUsingMoniker

public static ServerContext bindUsingMoniker(String moniker)
                                      throws AutomationException,
                                             IOException
Bind to a running instance of this class using the supplied ObjRef moniker

Parameters:
moniker - The ObjRef Moniker (Created using Windows CreateObjrefMoniker() and IMoniker->GetDisplayName).
Returns:
A reference to the running object.
Throws:
IOException - If there are communications problems.
AutomationException - If there was an error attaching to the instance.

getPropertyByName

public Object getPropertyByName(String name)
                         throws NoSuchFieldException,
                                IOException,
                                AutomationException
Get the value of a property dynamically at run-time, based on its name

Parameters:
name - The name of the property to get.
Returns:
The value of the property.
Throws:
NoSuchFieldException - If the property does not exit.
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

getPropertyByName

public Object getPropertyByName(String name,
                                Object rhs)
                         throws NoSuchFieldException,
                                IOException,
                                AutomationException
Get the value of a property dynamically at run-time, based on its name and a parameter

Parameters:
name - The name of the property to get.
rhs - A parameter used when getting the proxy.
Returns:
The value of the property.
Throws:
NoSuchFieldException - If the property does not exit.
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

invokeMethodByName

public Object invokeMethodByName(String name,
                                 Object[] parameters)
                          throws NoSuchMethodException,
                                 IOException,
                                 AutomationException
Invoke a method dynamically at run-time to pass primitive types (eg Integer to pass an int).

Parameters:
name - The name of the method to be invoked.
parameters - One element for each parameter. Use primitive type wrappers.
Returns:
The value returned by the method (null if none).
Throws:
NoSuchMethodException - If the method does not exit.
IOException - If there are communications problems.
AutomationException - If the remote server throws an exception.

invokeMethodByName

public Object invokeMethodByName(String name)
                          throws NoSuchMethodException,
                                 IOException,
                                 AutomationException
Throws:
NoSuchMethodException
IOException
AutomationException

getServerObject

public IServerObject getServerObject()
                              throws IOException,
                                     AutomationException
Description copied from interface: IServerContext
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.

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

createObject

public Object createObject(String cLSID)
                    throws IOException,
                           AutomationException
Description copied from interface: IServerContext
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()));

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

loadObject

public Object loadObject(String str)
                  throws IOException,
                         AutomationException
Description copied from interface: IServerContext
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));

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

saveObject

public String saveObject(Object obj)
                  throws IOException,
                         AutomationException
Description copied from interface: IServerContext
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));

Specified by:
saveObject in interface IServerContext
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
Description copied from interface: IServerContext
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.

Specified by:
getObject in interface IServerContext
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
Description copied from interface: IServerContext
Add an object running in the server context to the context's object dictionary.

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

remove

public void remove(String name)
            throws IOException,
                   AutomationException
Description copied from interface: IServerContext
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");

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

removeAll

public void removeAll()
               throws IOException,
                      AutomationException
Description copied from interface: IServerContext
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");

Specified by:
removeAll in interface IServerContext
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.

releaseContext

public void releaseContext()
                    throws IOException,
                           AutomationException
Description copied from interface: IServerContext
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();

Specified by:
releaseContext in interface IServerContext
Throws:
AutomationException - If the remote server throws an exception.
IOException - If there are communications problems.