com.esri.arcgis.server
Interface IServerObjectConfiguration

All Superinterfaces:
Serializable
All Known Subinterfaces:
IServerObjectConfiguration2, IServerObjectConfiguration3
All Known Implementing Classes:
IServerObjectConfiguration2Proxy, IServerObjectConfiguration3Proxy, IServerObjectConfigurationProxy, ServerObjectConfiguration

public interface IServerObjectConfiguration
extends Serializable

Provides access to administrators to members that control the behavior and properties of a server object configuration.

Remarks

The ArcGIS Server manages a set of server objects running across one or more host (container) machines. How those server objects are configured and run is defined by a set of server object configurations. Server object configurations can be added, removed and modified by users or developers who are members of the agsadmin users group, and therfore have administrator priviliges on the ArcGIS Server.

The IServerObjectConfiguration interface is a read/write interface on a server object configuration that allows administrators to configure new server object configurations to add to the server, update existing server object confiurations, and to view the configuration properties of a server object configuration.

Users and developers that are not part the the agsadmin user group do not have access to this interface. An additional read only interface called IServerObjectConfigurationInfo is available to non-administrators which provides read only access to a subset of the server object configuration's properties.

If you use IServerObjectConfiguration to modify any of a configuration's properties, you must call UpdateConfiguration on IServerObjectAdmin for those changes to be reflected in the server.

When To Use

Use the IServerObjectConfiguration interface to do the following:

Define a new server object configuration to be added to the server with the AddConfiguration method on IServerObjectAdmin

Update an existing server object configuration with the UpdateConfiguration method on IServerObjectAdmin

View the administrator level properties of an existing server object configuration. Administrator level properties are those that are not available through the IServerObjectConfigurationInfo interface, and include:

Properties that are available through bot the IServerObjectConfiguration (read/write) and IServerObjectConfigurationInfo (read only) interfaces include:

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

See Also:
IEnumServerObjectType, AGSLocatorWorkspace, IEnumServerObjectTypeInfo, GeocodeServer, ILocatorManager2.getAGSLocatorWorkspace(com.esri.arcgis.gisclient.IAGSServerConnectionName), ServerObject, ILocatorWorkspaceName2.getAGSServerConnectionName(), IPropertySet, AGSAddressLocator

Method Summary
 String getDescription()
          Description of the server object configuration.
 int getIsolationLevel()
          The isolation level of the server objects defined by the server object configuration.
 int getMaxInstances()
          The maximum number of server object instances for a server object configuration.
 int getMinInstances()
          The minimum number of server object instances for a server object configuration.
 String getName()
          Name of the server object configuration.
 IPropertySet getProperties()
          Initialization parameters and properties for the server objects created by the server object configuration.
 IPropertySet getRecycleProperties()
          The recycling properties for the server object configuration.
 int getStartupType()
          The startup type for this server object configuration.
 String getTypeName()
          Type of the server object configuration (MapServer or GeocodeServer).
 int getUsageTimeout()
          Maximum time (in seconds) a client can hold onto an instance of a server object for this server object configuration before releasing it back to the server.
 int getWaitTimeout()
          Maximum time (in seconds) a client will wait for an instance of a server object for this server object configuration using the CreateServerContext method on IServerObjectManager before timing out.
 boolean isPooled()
          Indicates whether the server objects defined by this configuration are pooled.
 void setDescription(String desc)
          Description of the server object configuration.
 void setIsolationLevel(int isoLevel)
          The isolation level of the server objects defined by the server object configuration.
 void setIsPooled(boolean isPooled)
          Indicates whether the server objects defined by this configuration are pooled.
 void setMaxInstances(int instances)
          The maximum number of server object instances for a server object configuration.
 void setMinInstances(int instances)
          The minimum number of server object instances for a server object configuration.
 void setName(String name)
          Name of the server object configuration.
 void setPropertiesByRef(IPropertySet props)
          Initialization parameters and properties for the server objects created by the server object configuration.
 void setRecyclePropertiesByRef(IPropertySet props)
          The recycling properties for the server object configuration.
 void setStartupType(int type)
          The startup type for this server object configuration.
 void setTypeName(String typeName)
          Type of the server object configuration (MapServer or GeocodeServer).
 void setUsageTimeout(int pVal)
          Maximum time (in seconds) a client can hold onto an instance of a server object for this server object configuration before releasing it back to the server.
 void setWaitTimeout(int pVal)
          Maximum time (in seconds) a client will wait for an instance of a server object for this server object configuration using the CreateServerContext method on IServerObjectManager before timing out.
 

Method Detail

getName

String getName()
               throws IOException,
                      AutomationException
Name of the server object configuration.

Remarks

The Name property in combination with the TypeName property is used to identify a server object configuration in methods such as GetConfiguration, UpdateConfiguration, StartConfiguration, etc.

Name is case-sensitive, and can have a maximum of 120 characters. Names can contain only the following characters:

A - Z
a - z
0 - 9
_ (undescore)
- (minus)

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The name
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setName

void setName(String name)
             throws IOException,
                    AutomationException
Name of the server object configuration.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
name - The name (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getTypeName

String getTypeName()
                   throws IOException,
                          AutomationException
Type of the server object configuration (MapServer or GeocodeServer).

Remarks

The TypeName property indicates the type of server object that this configuration creates and runs. Examples are MapServer and GeocodeServer.

The TypeName property in combination with the Name property is used to identify a server object configuration in methods such as GetConfiguration, UpdateConfiguration, StartConfiguration , etc.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The typeName
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setTypeName

void setTypeName(String typeName)
                 throws IOException,
                        AutomationException
Type of the server object configuration (MapServer or GeocodeServer).

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
typeName - The typeName (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getDescription

String getDescription()
                      throws IOException,
                             AutomationException
Description of the server object configuration.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The desc
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setDescription

void setDescription(String desc)
                    throws IOException,
                           AutomationException
Description of the server object configuration.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
desc - The desc (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getProperties

IPropertySet getProperties()
                           throws IOException,
                                  AutomationException
Initialization parameters and properties for the server objects created by the server object configuration.

Remarks

Server objects that are defined by server object configurations have a collection of initialization parameters and properties associated with them. An example of an initialization parameter is the map document associated with a MapServer object. An example of a property is the batch geocode size for a GeocodeServer object.

You can get these properties and change them using the Properties property on the server object configuration. The Properties property returns an IPropertySet. Use GetProperty, SetProperty on IPropertySet to get and set these properties. If you change these properties, you must call UpdateConfiguration to change them in the server object configuration.

You also use the Properties property to get a reference on the PropertySet for a new server object configuration to set its properties before adding it to the server by calling AddConfiguration.

The following are the properties for a MapServer object:

FilePath - the path to the map document that the MapServer will serve. This is a required property.

Example: \\machine\data\\usa.mxd

OutputDir - the location to which the MapServer will write its output. The OutputDir is typically a server directory. This is an optional property.

Example: \\machine\serveroutput

VirtualOutputDir - the virtual directory that corresponds to the OutputDir location. This is a required property if the OutputDir is specified.

Example: http://webserver/serveroutput

MaxRecordCount - the maximum number of records returned by the QueryFeatureData, Find and Identify methods on the MapServer. This is an optional property.

Example: 500

MaxBufferCount - the maximum number of features per layer that can be buffered at draw time when using the ExportMapImage on MapServer. This is an optional property.

Example: 100

MaxImageWidth- the maximum width of images (in pixels) that can be produced by ExportMapImage. This is an optional property.

Example: 2048

MaxImageHeight - the maximum height of images (in pixels) that can be produced by ExportMapImage. This is an optional property.

Example: 2048

The following are the properties for a GeocodeServer object:

Locator - the name of the locator that the GeocodeServer will serve. This is a required property.

Example: California

LocatorWorkspacePath - If the locator is a .loc or .mxs file, this is the path to the locator. This is a required property for locator files.

Example: \\machine\data\locators\

LocatorWorkspaceConnectionString - If the locator is an SDE locator, then this is the SDE connection string. This is a required property for SDE locators.

Example: SERVER=machine;INSTANCE=5151;DATABASE=gdb;USER=gdb;PASSWORD=gdb;VERSION=sde.DEFAULT

SuggestedBatchSize - the number of records that the GeocodeServer object will process at one time when performing batch geocoding.

Example: 500

MaxBatchSize - the maximum number of records that can be input into the GeocodeAddresses method. This is an optional property.

Example: 10000

MaxResultSize - the maximum number of candidates resturned by the FindAddressCandidates method. This is an optional property.

Example: 500

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.system.IPropertySet
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPropertySet.getCount(), com.esri.arcgis.system.propertySet, IPropertySet.removeProperty(String), IPropertySet, IPropertySet.isEqual(com.esri.arcgis.system.IPropertySet)

setPropertiesByRef

void setPropertiesByRef(IPropertySet props)
                        throws IOException,
                               AutomationException
Initialization parameters and properties for the server objects created by the server object configuration.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
props - A reference to a com.esri.arcgis.system.IPropertySet (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getRecycleProperties

IPropertySet getRecycleProperties()
                                  throws IOException,
                                         AutomationException
The recycling properties for the server object configuration.

Remarks

Pooled server objects are typically shared between multiple applications and users of those applications. Through reuse, a number of things can happen to a server object to make them unavailable for use by applications. For example, an application may incorrectly modify a server objects state, or an application may incorrectly hold a reference to a server object, making it unavailable to other applications or sessions. In some cases, server object may become corrupted and unusable.

Recycling allows for server objects that have become un-usable to be destroyed and replaced with fresh server objects, and to reclaim resources taken up by stale server objects. This process allows you to keep the pool of server objects fresh, and cycle out stale or unusable server objects.

You can get the recycling properties and change them using the RecyclingProperties property on the server object configuration. The RecyclingProperties property returns an IPropertySet. Use GetProperty, SetProperty on IPropertySet to get and set these properties. If you change these properties, you must call UpdateConfiguration to change them in the server object configuration.

You also use the RecyclingProperties property to get a reference on the PropertySet for a new server object configuration to set its properties before adding it to the server by calling AddConfiguration.

The properties associated with recylcing are:

StartTime which is time at which the recycling interval is initialized. The time specified is in 24 notation. For example, to set the start time at 2pm, the StartTime property would be 14:00.

Interval which defines the the time between recycling operations in seconds. For example, to recycle the configuration every hour, this property would be set to 3600.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.system.IPropertySet
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPropertySet

setRecyclePropertiesByRef

void setRecyclePropertiesByRef(IPropertySet props)
                               throws IOException,
                                      AutomationException
The recycling properties for the server object configuration.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
props - A reference to a com.esri.arcgis.system.IPropertySet (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getMinInstances

int getMinInstances()
                    throws IOException,
                           AutomationException
The minimum number of server object instances for a server object configuration.

Remarks

The MinInstances property represents the number of server object instances that are pre-loaded when the server object configuration is started. The GIS server will ensure that the minimum number of instances are always running within the server for a given configuration.

When there are more simultaneous requests that server object instances running, additional server object instances will be started until MaxInstances is reach.

The MinInstances property must be less than the MaxInstances property.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The instances
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setMinInstances

void setMinInstances(int instances)
                     throws IOException,
                            AutomationException
The minimum number of server object instances for a server object configuration.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
instances - The instances (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getMaxInstances

int getMaxInstances()
                    throws IOException,
                           AutomationException
The maximum number of server object instances for a server object configuration.

Remarks

The MaxInstances property indicates the maximum number of server objects that can be running and handle requests at any one time. if the maximum number of server objects are running and busy, additional requests will be queued until a server object becomes free.

For a pooled server object, the MaxInstances represents the maximum simultaneus requests that can be processed by the server object configuration. For a non-pooled server object, the MaxInstances represents the maximum number of simlutaneus application users of that particular server object configuration.

The MaxInstances property must be greater than 0 and must be greater than the MinInstances property.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The instances
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setMaxInstances

void setMaxInstances(int instances)
                     throws IOException,
                            AutomationException
The maximum number of server object instances for a server object configuration.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
instances - The instances (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isPooled

boolean isPooled()
                 throws IOException,
                        AutomationException
Indicates whether the server objects defined by this configuration are pooled.

Remarks

Server objects can be either pooled or non-pooled. Pooled server objects can be shared accross multiple sessions and applications and are held onto by an application for the duration of a single request. Pooled server objects are meant for applications that make stateless use of those objects.

Non-pooled server objects are dedicated to a single application session and are held onto for the duration of an application session. Non-pooled server objects are not shared between application sessions, and are meant for applications that make stateful use of those objects.

Use the IsPooled property to indicate if the server objects created by this server object configuration are pooled or non-pooled. When StartConfguration is called on a server object configuration whose IsPooled property is true a set of server objects will be pre-loaded based on the MinInstances property of the server object configuration.

When StartConfiguration is called on a server object configuration whose IsPooled property is false, no server objects are pre-loaded. Server objects are loaded and initialized when an application gets one from the server using CreateServerContext.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The isPooled
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setIsPooled

void setIsPooled(boolean isPooled)
                 throws IOException,
                        AutomationException
Indicates whether the server objects defined by this configuration are pooled.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
isPooled - The isPooled (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getIsolationLevel

int getIsolationLevel()
                      throws IOException,
                             AutomationException
The isolation level of the server objects defined by the server object configuration.

Remarks

Server objects can have either high isolation (esriServerIsolationLevelHigh) or low isolation (esriIsolationLevelLow ). Each instance of a server object with high isolation run in s a dedicated process on the server that it does not share with other server objects. Instances of server objects with low isolation may share the same process with other server object instances of the same configuration.

Use the IsolationLevel property to get the server object isolation, or set it for a new configuration or to update an existing configuration.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A com.esri.arcgis.server.esriServerIsolationLevel constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setIsolationLevel

void setIsolationLevel(int isoLevel)
                       throws IOException,
                              AutomationException
The isolation level of the server objects defined by the server object configuration.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
isoLevel - A com.esri.arcgis.server.esriServerIsolationLevel constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getStartupType

int getStartupType()
                   throws IOException,
                          AutomationException
The startup type for this server object configuration. Startup type describes whether the server object configuration is started when the server object manager service is started for the GIS server.

Remarks

The StartupType indicates if the configuration is automatically started (esriSTAutomatic) when the server object manager windows or UNIX service is started. Server object configuraitons that are not configured to startup automatically (esriSTManual) must be started manually using ArcCatalog, or by calling the StartConfiguration method on IServerObjectAdmin.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A com.esri.arcgis.server.esriStartupType constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setStartupType

void setStartupType(int type)
                    throws IOException,
                           AutomationException
The startup type for this server object configuration. Startup type describes whether the server object configuration is started when the server object manager service is started for the GIS server.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
type - A com.esri.arcgis.server.esriStartupType constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getWaitTimeout

int getWaitTimeout()
                   throws IOException,
                          AutomationException
Maximum time (in seconds) a client will wait for an instance of a server object for this server object configuration using the CreateServerContext method on IServerObjectManager before timing out.

Remarks

The amout of time it takes between a client requesting a server object (using the CreateServerContext method on IServerObjectManager) and getting a server object is called the wait time. A server object can be configured to have a maximum wait time by specifying the WaiteTimeout property on IServerObjectConfiguration. If a clientís wait time exceeds the maximum wait time for a server object, then their request will timeout.

The WaiteTimeout property is in seconds.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The pVal
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setWaitTimeout

void setWaitTimeout(int pVal)
                    throws IOException,
                           AutomationException
Maximum time (in seconds) a client will wait for an instance of a server object for this server object configuration using the CreateServerContext method on IServerObjectManager before timing out.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
pVal - The pVal (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getUsageTimeout

int getUsageTimeout()
                    throws IOException,
                           AutomationException
Maximum time (in seconds) a client can hold onto an instance of a server object for this server object configuration before releasing it back to the server. It is the maximum time allowed between calling CreateServerContext and ReleaseServerContext.

Remarks

Once a client gets a reference to a server object, they can hold onto that server object as long as they want to before releasing it. The amount of time between when a client gets a reference to a server object and when they release it is called the usage time. To ensure that clients donít hold references to server objectís for too long (i.e. they donít correctly release server objects), A server object can be configured to have a maximum usage time by specifying the UsageTimeout property on IServerObjectConfiguration. If a client holds onto a server object longer than the maximum usage time, then the server object is automatically released and the client will lose their reference to the server object.

The UsageTimeout is in seconds.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The pVal
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setUsageTimeout

void setUsageTimeout(int pVal)
                     throws IOException,
                            AutomationException
Maximum time (in seconds) a client can hold onto an instance of a server object for this server object configuration before releasing it back to the server. It is the maximum time allowed between calling CreateServerContext and ReleaseServerContext.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
pVal - The pVal (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.