com.esri.arcgis.server

Interface IServerObjectExtension

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

IServerObjectExtensionProxy, WFSServer

public interface IServerObjectExtension
extends java.io.Serializable

Provides access to the members that control a server object extension.

Remarks

Server objects may have extensions that extend their base functionality for more specialized uses. Each type of server object may have a set of extensions that can be enabled or disabled based on its configuration. ArcGIS Server includes some server object extensions out of the box, and developers can extend ArcGIS Server by writing their own server object extensions.

Server objects extensions also have SOAP interfaces for handling SOAP requests to execute methods and returning results as SOAP responses. This support for SOAP request handling makes it possible to expose server object extensions as Web services that can be consumed by clients across the Internet.

Developers can create their own server object extensions. The goal of creating a server object extension is to provide coarse-grained methods that do a lot of work in the server, rather than pay the cost of making a large number of calls into the server from the client.

Extending a server object over creating a generic COM object that is created on demand in the server context has the following advantages:

1. Developers don’t need to explicitly create instances of a server object extension in a context. The server object extension is created by the GIS server when the server object instance itself is created.
   
2. If the functionality that is exposed by the extension requires resources that can be costly to aquire, the initialization cost of the creating the object is paid once when the server object and its extensions are initially created.
   
3. If the functionionality that is exposed by the extension can benfit from some caching logic, its possible to implement such logic becuase the cache will remain for as long as the server object instance itself remains in the pool.
   
4. The ArcGIS Server administration applications can be extended to include custom properties dialogs for configuring custom extensions for specific server object configurations.
   
5. Unlike utility COM objects, server object extensions are reigstered and configured with speficic server objects and are not for add-hoc use or use with an empty server context.

The process for creating a server object extensions is the following:

• Create a COM object that implements IServerObjectExtension, and includes any addtional custom interfaces and methods. Optionally implement IObjectConstruct, ILogSupport and IObjectActivate.
  
• Optionally create a COM object that implements IAGSSOEParameterPage and ICOMPropertyPage that includes a user form that encapsulates any initialization properties that must be configured for the extension.
  
• Register the server extension COM object created in step 1 on each container machine, the server object manager machine and any client machines (i.e. Web servers, ArcGIS Desktop machines that administer the GIS server).
  
• Register the server object extension with the GIS server (using the AddExtensionType method on IServerObjectAdmin2).
  
• Optionally register the property page created in step 2 in the AGS Extension Parameter Pages component category on each ArcGIS desktop client machine.
  
• Create a new server object configuration that includes the server object extension.
  
• Create your application that consumes the server object and its extension. Each of these steps will be illustrated using the same example as was used for the utility COM object.

IServerObjectExtension is a mandatory interface that must be supported by all server object extensions, and includes two methods: Init and Shutdown. This interface is used by the server object to manage the lifetime of the server object extension. The server object cocreates the server object extension and calls the Init method handing it a back reference to the server object via the server object helper argument. The server object helper implements a weak reference on the server object. The extension can keep a strong reference on the server object helper (for example, in a member variable) but should not keep a strong reference on the server object. Extensions should get the server object from the server object helper in order to make any method calls on the server object and release the reference after making the method calls. Init is called once when the instance of the server object extension is created.

The Shutdown method informs the server object extension that the server object’s context is being shutdown and is about to go away. In response the server object extension should release its reference on the server object helper:

private IServerObjectHelper m_SOH;

public void Init(IServerObjectHelper pSOH)

{

  m_SOH = pSOH;

}

public void Shutdown()

{

  m_SOH = null;

}

In your custom methods, you use the server object helper to get a reference to the server object, for example:

IMapServer mapsrv = m_SOH.ServerObject as IMapServer;

Your server object extension can also optionally implement IObjectConstruct, IObjectActivate and ILogSupport.

When To Use

The IServerObjectExtension interface is used by developers who want to create their own server object extensions.

Product Availability

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

Method Summary

Modifier and Type	Method and Description
void	init(IServerObjectHelper pSOH) Initializes and starts the server object specified by the IServerObjectHelper reference.
void	shutdown() Stops the server object specified by the IServerObjectHelper reference.

Method Detail

init

void init(IServerObjectHelper pSOH)
   throws java.io.IOException,
          AutomationException

Initializes and starts the server object specified by the IServerObjectHelper reference.

Product Availability

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

Parameters:

pSOH - A reference to a com.esri.arcgis.server.IServerObjectHelper (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

shutdown

void shutdown()
       throws java.io.IOException,
              AutomationException

Stops the server object specified by the IServerObjectHelper reference.

Product Availability

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

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.