IServerObjectConfiguration Interface

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

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
• RecycleProperties
• MinInstances
• MaxInstances
• IsolationLevel
• StartupType
• WaitTimeout
• UsageTimeout

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

• Name
• TypeName
• Description
• IsPooled

Members

	Name	Description
	Description	Description of the server object configuration.
	IsolationLevel	The isolation level of the server objects defined by the server object configuration.
	IsPooled	Indicates whether the server objects defined by this configuration are pooled.
	MaxInstances	The maximum number of server object instances for a server object configuration.
	MinInstances	The minimum number of server object instances for a server object configuration.
	Name	Name of the server object configuration.
	Properties	Initialization parameters and properties for the server objects created by the server object configuration.
	RecycleProperties	The recycling properties for the server object configuration.
	StartupType	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.
	TypeName	Type of the server object configuration (MapServer or GeocodeServer).
	UsageTimeout	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.
	WaitTimeout	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.

IServerObjectConfiguration.Description Property

Description of the server object configuration.

Public Property Description As String

public string Description {get; set;}

IServerObjectConfiguration.IsolationLevel Property

The isolation level of the server objects defined by the server object configuration.

Public Property IsolationLevel As esriServerIsolationLevel

public esriServerIsolationLevel IsolationLevel {get; set;}

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.

IServerObjectConfiguration.IsPooled Property

Indicates whether the server objects defined by this configuration are pooled.

Public Property IsPooled As Boolean

public bool IsPooled {get; set;}

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 IsPooledproperty 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.

IServerObjectConfiguration.MaxInstances Property

The maximum number of server object instances for a server object configuration.

Public Property MaxInstances As Integer

public int MaxInstances {get; set;}

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.

IServerObjectConfiguration.MinInstances Property

The minimum number of server object instances for a server object configuration.

Public Property MinInstances As Integer

public int MinInstances {get; set;}

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.

IServerObjectConfiguration.Name Property

Name of the server object configuration.

Public Property Name As String

public string Name {get; set;}

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 - Za - z0 - 9_ (undescore)- (minus)

IServerObjectConfiguration.Properties Property

Initialization parameters and properties for the server objects created by the server object configuration.

Public Property Properties As IPropertySet

public IPropertySet Properties {get; set;}

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

IServerObjectConfiguration.RecycleProperties Property

The recycling properties for the server object configuration.

Public Property RecycleProperties As IPropertySet

public IPropertySet RecycleProperties {get; set;}

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.

IServerObjectConfiguration.StartupType Property

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.

Public Property StartupType As esriStartupType

public esriStartupType StartupType {get; set;}

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.

IServerObjectConfiguration.TypeName Property

Type of the server object configuration (MapServer or GeocodeServer).

Public Property TypeName As String

public string TypeName {get; set;}

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.

IServerObjectConfiguration.UsageTimeout Property

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.

Public Property UsageTimeout As Integer

public int UsageTimeout {get; set;}

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 UsageTimeoutproperty onIServerObjectConfiguration. 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.

IServerObjectConfiguration.WaitTimeout Property

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.

Public Property WaitTimeout As Integer

public int WaitTimeout {get; set;}

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 WaiteTimeoutproperty onIServerObjectConfiguration. If a client�s wait time exceeds the maximum wait time for a server object, then their request will timeout.

The WaiteTimeoutproperty is in seconds.

Classes that implement IServerObjectConfiguration

Classes	Description

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.