IServerObjectAdmin Interface

Provides access to members that administer the ArcGIS server.

Description

IServerObjectAdminprovides methods to retrieve server configuration information and to administer the ArcGIS Server.

The IServerObjectAdmininterface can be obtained by a call to GISServerConnection.ServerObjectAdmin.

When To Use

Use the IServerObjectAmin interface when your application connects to the ArcGIS Server to administer the server's set of server object configurations and server object types, and for administering aspects of the server itself, such as the list of machines that may host server objects.

If your application is connecting to the server to make use of objects in the server, use the IServerObjectManager interface.

Members

	Name	Description
	AddConfiguration	Adds a server object configuration (created with CreateConfiguration) to the GIS server.
	AddMachine	Adds a host machine (created with CreateMachine) to the GIS server.
	AddServerDirectory	Adds a server directory (created with CreateServerDirectory) to the GIS server.
	CreateConfiguration	Creates a new server object configuration.
	CreateMachine	Creates a new host machine.
	CreateServerDirectory	Creates a new server directory.
	DeleteConfiguration	Deletes a server object configuration from the GIS server.
	DeleteMachine	Deletes a host machine from the GIS server, making it unavailable to host server objects.
	DeleteServerDirectory	Deletes a server directory such that its cleanup is no longer managed by the GIS server. It does not delete the physical directory from disk.
	GetConfiguration	Get the server object configuration with the specified Name and TypeName.
	GetConfigurations	An enumerator over all the server object configurations.
	GetConfigurationStatus	Get the configuration status for a server object configuration with the specified Name and TypeName.
	GetMachine	Get the host machine with the specified Name.
	GetMachines	An enumerator over all the GIS server's host machines.
	GetServerDirectories	An enumerator over the GIS server's output directories.
	GetServerDirectory	Get the server directory with the specified Path.
	GetTypes	An enumerator over all the server object types.
	PauseConfiguration	Makes the configuration unavailable to clients for processing requests, but does not shut down running instances of server objects, or interrupt requests in progress.
	Properties	The properties for the GIS server.
	StartConfiguration	Starts a server object configuration and makes it available to clients for processing requests.
	StopConfiguration	Stops a server object configuration and shuts down any running instances of server objects defined by the configuration.
	UpdateConfiguration	Updates the properties of a server object configuration.
	UpdateMachine	Updates the properties of a host machine.
	UpdateServerDirectory	Updates the properties of a server directory.

IServerObjectAdmin.AddConfiguration Method

Adds a server object configuration (created with CreateConfiguration) to the GIS server.

Public Sub AddConfiguration ( _
    ByVal config As IServerObjectConfiguration _
)

public void AddConfiguration (
    IServerObjectConfiguration config
);

Remarks

The AddConfiguration method will add a ServerObjectConfiguration to your ArcGIS Server. A new ServerObjectConfiguration can be created using the CreateConfiguration method. Use the IServerObjectConfiguration interface to set the various properties of the configuration, then use the AddConfiguration method on IServerObjectAdmin to add the new configuration to the ArcGIS Server.

Once a configuration is added to the server, you can use StartConfiguration to make it available for applications to use.

IServerObjectAdmin.AddMachine Method

Adds a host machine (created with CreateMachine) to the GIS server.

Public Sub AddMachine ( _
    ByVal Machine As IServerMachine _
)

public void AddMachine (
    IServerMachine Machine
);

Remarks

ArcGIS Server is a distributed system. Server objects managed by the GIS server run on one or more host machines. A machine that can host server objects must have the Server Object Container installed on it, and the machine must be added to the list of host machines managed by the Server Object Manager (SOM).

Use the AddMachine method to add new host machines to your GIS server. Once a machine has been added to the GIS server, as new server object instances are created, the SOM will make use of the new machine.

IServerObjectAdmin.AddServerDirectory Method

Adds a server directory (created with CreateServerDirectory) to the GIS server.

Public Sub AddServerDirectory ( _
    ByVal pSD As IServerDirectory _
)

public void AddServerDirectory (
    IServerDirectory pSD
);

Remarks

Both server objects and server applications typically need to write either temporary data or result data to some location in order for it to be delivered to, or presented to the end user. For example, a map server object's ExportMapImage method can create a image file which is then displayed on a web applicaiton. These files are typically transient and temporary by nature. For example, when a map server write's an image to satisfy a request from a web application, that image is needed only for the time it takes to display it on the web application. An application that creates check out personal geodatabases for download would provide a finite amount of time between which that geodatabase is created and when it can be downloaded.

Because server applications support many user sessions, these output files can accumulate and need to be periodically cleaned up. The server provides the cabability to automatically cleanup these output files if they are written to one of the server's output directories.

Use the CreateServerDirectory method to create a new server directory that you can pass as an argument to the AddServerDirectory method to add new server directories to your GIS Server. Once you have added the server directory, you can configure your server objects and server applications to make use of the server directory.

Note: server directories must be accessible by all host machines configured in the GIS server.

IServerObjectAdmin.CreateConfiguration Method

Creates a new server object configuration.

Public Function CreateConfiguration ( _
) As IServerObjectConfiguration

public IServerObjectConfiguration CreateConfiguration (
);

Remarks

The CreateConfiguration method will create a new ServerObjectConfiguration that you can add to your ArcGIS Server. The CreateConfiguration method returns the IServerObjectConfiguration interface on the new ServerObjectConfiguration. Use the IServerObjectConfiguration interface to set the various properties of the configuration, then use the AddConfiguration method on IServerObjectAdmin to add the new configuration to the ArcGIS Server.

Once a configuration is added to the server, you can use the StartConfiguration and EnableConfiguration to make it available for applications to use.

IServerObjectAdmin.CreateMachine Method

Creates a new host machine.

Public Function CreateMachine ( _
) As IServerMachine

public IServerMachine CreateMachine (
);

Remarks

Use the CreateMachine method to create a new server machine that you can pass as an argument to the AddMachine method to add new host machines to your GIS server.

IServerObjectAdmin.CreateServerDirectory Method

Creates a new server directory.

Public Function CreateServerDirectory ( _
) As IServerDirectory

public IServerDirectory CreateServerDirectory (
);

Remarks

Note: server directories must be accessible by all host machines configured in the GIS server.

IServerObjectAdmin.DeleteConfiguration Method

Deletes a server object configuration from the GIS server.

Public Sub DeleteConfiguration ( _
    ByVal Name As String, _
    ByVal TypeName As String _
)

public void DeleteConfiguration (
    string Name,
    string TypeName
);

Remarks

Use DeleteConfiguration to delete a server object configuration from you GIS Server. Note, in order to call DeleteConfiguration, the server object configuration must be stopped. If it is not stopped, then DeleteConfiguration will return an error.

IServerObjectAdmin.DeleteMachine Method

Deletes a host machine from the GIS server, making it unavailable to host server objects.

Public Sub DeleteMachine ( _
    ByVal MachineName As String _
)

public void DeleteMachine (
    string MachineName
);

Remarks

The DeleteMachine method removes a machine from the machines that can host server objects for the GIS server. When you delete a machine, any instances of server objects that are running on that machine will be shut down and replaced with instances running on the GIS server's other host machines.

IServerObjectAdmin.DeleteServerDirectory Method

Deletes a server directory such that its cleanup is no longer managed by the GIS server. It does not delete the physical directory from disk.

Public Sub DeleteServerDirectory ( _
    ByVal Path As String _
)

public void DeleteServerDirectory (
    string Path
);

Remarks

The DeleteServerDirectory method removes a directory from the set of directories managed by the GIS server. The DeleteServerDirectory method will not affect the physical directory.

When a server directory is removed with this method, the GIS Server will not longer manage the cleanup of output files written to that directory. Applicaitons or server objects that are configured to write their output to the physical directory that is referenced by the server directory will continue to work, but the files they write will not be cleaned up by the server.

IServerObjectAdmin.GetConfiguration Method

Get the server object configuration with the specified Name and TypeName.

Public Function GetConfiguration ( _
    ByVal Name As String, _
    ByVal TypeName As String _
) As IServerObjectConfiguration

public IServerObjectConfiguration GetConfiguration (
    string Name,
    string TypeName
);

Remarks

The GetConfiguration method returns the IServerObjectConfiguration interface on the ServerObjectConfiguration specified by name and type. Once you have a reference to the ServerObjectConfiguration, you can get and set its properties, and use it as input the UpdateConfiguration method.

IServerObjectAdmin.GetConfigurations Method

An enumerator over all the server object configurations.

Public Function GetConfigurations ( _
) As IEnumServerObjectConfiguration

public IEnumServerObjectConfiguration GetConfigurations (
);

Remarks

GetConfigurationsreturns an enumeration (IEnumServerObjectConfiguration) of IServerObjectConfigurationfor configurations of any esriConfigurationStatus from all folders.

These Info objects provide information about the server object configurations and types that are required to make use of them in an application.

IServerObjectAdmin.GetConfigurationStatus Method

Get the configuration status for a server object configuration with the specified Name and TypeName.

Public Function GetConfigurationStatus ( _
    ByVal Name As String, _
    ByVal TypeName As String _
) As IServerObjectConfigurationStatus

public IServerObjectConfigurationStatus GetConfigurationStatus (
    string Name,
    string TypeName
);

Remarks

The GetConfigurationStatus method will return the IServerObjectConfigurationStatus interface on a particular server object configuration. This interface provides information as to the number of instances of that configuration that are running, and the number in use. It provides information as to the startup status of the configuration.

You can use this interface to monitor server object configuration usage. For example, you can use the InstanceInUseCount to determine if any instances of the configuration are in use before stopping the configuration.

IServerObjectAdmin.GetMachine Method

Get the host machine with the specified Name.

Public Function GetMachine ( _
    ByVal Name As String _
) As IServerMachine

public IServerMachine GetMachine (
    string Name
);

Remarks

The GetMachine method returns the IServerMachine interface on the ServerMachine whoes name is specified. Once you have a reference to the ServerMachine, you can get and set its description, and use it as input the UpdateMachine method.

IServerObjectAdmin.GetMachines Method

An enumerator over all the GIS server's host machines.

Public Function GetMachines ( _
) As IEnumServerMachine

public IEnumServerMachine GetMachines (
);

Remarks

A server object configuration can be configured such that its server objects run on one or more host machines that have been added to the ArcGIS Server. Use the GetMachines method to get the names of the machines that have been added to the server to host server objects.

IServerObjectAdmin.GetServerDirectories Method

An enumerator over the GIS server's output directories.

Public Function GetServerDirectories ( _
) As IEnumServerDirectory

public IEnumServerDirectory GetServerDirectories (
);

Remarks

Both server objects and server applicaitons typically need to write either temporary data or result data to some location in order for it to be delivered to, or presented to the end user. For example, a map server object's ExportMapImage method can create a image file which is then displayed on a web applicaiton. These files are typically transient and temporary by nature. For example, when a map server writes an image to satisfy a request from a web application, that image is needed only for the time it takes to display it on the web application. An application that creates check out personal geodatabases for download would provide a finite amount of time between which that geodatabase is created and when it can be downloaded.

The GetServerDirectories method returns a enumeration of all the server directories that are managed by the server.

IServerObjectAdmin.GetServerDirectory Method

Get the server directory with the specified Path.

Public Function GetServerDirectory ( _
    ByVal Path As String _
) As IServerDirectory

public IServerDirectory GetServerDirectory (
    string Path
);

Remarks

The GetServerDirectory method returns the IServerDirectory interface on the ServerDirectory whose path is specified. Once you have a reference to the ServerDirectory, you can get and set its properties, and use it as input the UpdateServerDirectery method.

IServerObjectAdmin.GetTypes Method

An enumerator over all the server object types.

Public Function GetTypes ( _
) As IEnumServerObjectType

public IEnumServerObjectType GetTypes (
);

Remarks

The GetTypes methid returns an enumeration of the server object types that are installed in the GIS Server. By default, the MapServer and GeocodeServer object types are installed in the server.

IServerObjectAdmin.PauseConfiguration Method

Makes the configuration unavailable to clients for processing requests, but does not shut down running instances of server objects, or interrupt requests in progress.

Public Sub PauseConfiguration ( _
    ByVal Name As String, _
    ByVal TypeName As String _
)

public void PauseConfiguration (
    string Name,
    string TypeName
);

Remarks

The PauseConfiguration method will pause the server object configuration. Pausing the configuration does not interupt any requests that are being executed by instances of server objects managed by that configuration. A paused server object, hevever, will refuse future requests.

You should pause server objects if you want to lock requests from being processed, but you want requests in process to complete. Once all objects are not longer in use, you can perform necessary operations (such as database maintenance, stopping the server object configuration to changes properties, etc). Use the GetConfigurationStatus and IServerObjectConfigurationStatus to determine if any server objects are in use.

Use the StartConfiguration method to resume the server object configuration.

IServerObjectAdmin.Properties Property

The properties for the GIS server.

Public Property Properties As IPropertySet

public IPropertySet Properties {get; set;}

Remarks

The Properties property on IServerObjectAdmin returns the logging properties for the GIS server. The properties are for the GIS server's logging, and for server object creation timeout.

The GIS server logs its activity, including server object configuration sartup, shutdown, server context creation and shutdown, as well as errors generated through any failed operation or request in the GIS server.

You can control the logging properties through the PropertySet returned by Properties. The following is a description of the logging properties:

LogPath: this is the path to the location on disk that log files are writeen. By default, the LogPath is <install location>\log

LogSize: this is the size to which a single log file can graw (in MB) before a new logfile is created. By default, the LogSize is 10

LogLevel: this is a number between 0 and 5 which indicates the level of detail that the server logs. By default, the LogLevel is 3. The following is a description of the each log level:

0 (None): No logging
1 (Error): Serious problems that require immediate attention
2 (Warning): Problems that require attention
3 (Normal): Common administrative messages of the server
4 (Detailed): Very common messages from user use of the server, including server objects
5 (Debug): verbose messages to aid in troubleshooting

All aspects of logging can be changed when the GIS server is running. When they are changed, the server will immediatly use the new logging settings.

Server object creation may hang for a variety of reasons. To prevent this from adversly affecting the GIS server, it has a ConfigurationStartTimeout property which defines the maximim time in seconds a server object instance has to initialize itself before its creation is cancelled.

IServerObjectAdmin.StartConfiguration Method

Starts a server object configuration and makes it available to clients for processing requests.

Public Sub StartConfiguration ( _
    ByVal Name As String, _
    ByVal TypeName As String _
)

public void StartConfiguration (
    string Name,
    string TypeName
);

Remarks

The start configuration method will start the server object configuration and make it available for use by clients. When a server object configuration is started, if it is a pooled configuration, the minimum number of server objects as described by the configuration will be pre-loaded. The StartConfiguration method will complete only when all the server object instances have been created to satisfy the minimum.

IServerObjectAdmin.StopConfiguration Method

Stops a server object configuration and shuts down any running instances of server objects defined by the configuration.

Public Sub StopConfiguration ( _
    ByVal Name As String, _
    ByVal TypeName As String _
)

public void StopConfiguration (
    string Name,
    string TypeName
);

Description

The StopConfigurationmethod stops a server object configuration. Stopping a server object configuration both makes the server object configuration unusable by clients (calls to CreateServerObject referencing the configuration will fail), and it also shuts down any of the confiuration's running server objects. If any of those objects are in use and executing requests, they will be interupted and shut down.

You should stop a configuration when you need to change its properties (such as pooling model or recycling model). Use the StartConfiguration method to re-start the configuration.

If you want to stop the confuguration without interupting clients which are making use of server objects, you can pause the configuration using PauseConfiguration and wait until such a time that all server object usage has ended, then call StopConfiguration to stop the configuration.

IServerObjectAdmin.UpdateConfiguration Method

Updates the properties of a server object configuration.

Public Sub UpdateConfiguration ( _
    ByVal config As IServerObjectConfiguration _
)

public void UpdateConfiguration (
    IServerObjectConfiguration config
);

Remarks

The UpdateConfiguration method will update the ServerObjectConfiguration that is specified when the method is called. You can use the GetConfiguration or GetConfigurations methods on IServerObjectAdmin to get a reference to the ServerObjectConfiguration you want to update.

Note that the server object configuration must be stopped before you call UpdateConfiguration. You can use StopConfiguration to stop the server object configuration.

IServerObjectAdmin.UpdateMachine Method

Updates the properties of a host machine.

Public Sub UpdateMachine ( _
    ByVal Machine As IServerMachine _
)

public void UpdateMachine (
    IServerMachine Machine
);

Remarks

The UpdateMachine method will update the host machine that is specified when the method is called. You can use the GetMachine or GetMachines methods on IServerObjectAdmin to get a reference to the machine you want to update.

The UpdateMachineis useful for modifying the machine's description.

IServerObjectAdmin.UpdateServerDirectory Method

Updates the properties of a server directory.

Public Sub UpdateServerDirectory ( _
    ByVal pSD As IServerDirectory _
)

public void UpdateServerDirectory (
    IServerDirectory pSD
);

Remarks

The UpdateServerDirectory method will update the ServerDirectory that is specified when the method is called. You can use the GetServerDirectory or GetServerDirectories methods on IServerObjectAdmin to get a reference to the ServerDirectory you want to update.

The UpdateServerDirectoryis useful for modifying the cleanup mode (CleaningMode ) and cleanup schedule.

Note: server directories must be accessible by all host machines configured in the GIS server.

Classes that implement IServerObjectAdmin

Classes	Description

Remarks

Any application that runs as a user account in the agsadminuser group on the ArcGIS Server can use the IGISServerConnection interface to connect to the ArcGIS Server and to get a reference to the ServerObjectAdmin. If the user account is not part of the agsadmin user group, the ServerObjectAdmin property on IServerConnection will return an error. Applications that are running as accounts that can connect to the server but are not part of the agsadmin user group can use the ServerObjectManagerproperty on IGISServerConnection to get a reference on the ServerObjectManager.

The IServerObjectAdmin interface has the necessary methods for an application to adminstrate both the set of server object configurations and types associated with the server, and to administer aspects of the server itself. The following administration functionality of the ArcGIS Server is exposed by methods and properties on IServerObjectAdmin:

Adminster server object configurations:

Add and delete server object configurations
Update a server object configuration's properties
Start, stop, and pause server object configurations
Report the status of a server object configuration
Get all server object configurations and their properties
Get all server object types and their properties

Administer aspects of the server itself:

Add and remove server container machines
Get all server container machines
Add and remove server directories
Get all server directories
Configure the server's logging properties