04-概述开发 SOEs

 

Developing SOEs

可以通过实现com.esri.arcgis.server.IServerObjectExtension接口来定义服务器对象扩展。

对于SOE，此接口是必需的，并且包括两个方法：init（）和shutdown（）。服务器对象使用此接口来管理SOE的生存期。服务器对象创建SOE并调用init（）方法，并通过ServerObjectHelper参数将对它的引用交还给服务器对象。 ServerObjectHelper在服务器对象上实现了一个弱引用，该引用不受垃圾收集器的保护。该扩展可以在服务器对象帮助器上保留强引用（例如，在成员变量中），但是不建议这样做，因为强引用会导致不必要的对象保留在内存中并影响性能。扩展应该从服务器对象帮助器获取服务器对象，以便在服务器对象上进行任何方法调用，然后在进行方法调用后释放引用。

创建SOE实例后，将调用一次init（）方法。像init（）方法一样，shutdown（）方法仅被调用一次，并通知SOE服务器对象的上下文正在关闭并且即将消失。作为响应，SOE应该在服务器对象帮助器上释放其引用。任何日志条目仅是信息性的，是可选的。有关SOE日志记录的信息，请参阅日志消息主题（Log messages）。

SOE annotations

在Java SOE中使用注释来指示Java类是ArcGIS扩展，并保存ArcGIS Server在运行时部署和管理SOE所需的元数据。在ArcGIS 10.1及更高版本中，Java SOE支持两种类型的注释：

@ArcGIS Extension

@ArcGISExtension批注指示带批注的接口或类作为ArcGIS扩展自动显示给ArcGIS平台。 @ArcGISExtension批注被ArcGIS用作一种将您的接口和类作为扩展进行关联的方式，而无需在某些外部源中嵌入任何配置或API调用。以下是SOE的带注释的接口和类的示例：

// Custom Interface
@ArcGISExtension
public interface IMySoeInterface{
    public String mySoeFoo();
}

// SOE class
@ArcGISExtension
public class SOE implements IServerObjectExtension, IMySoeInterface{
    // IServerObjectExtension methods
    public void init(IServerObjectHelper arg0)throws IOException,
        AutomationException{
        // Called once when the instance of the SOE is created
    }
    public void shutdown()throws IOException, AutomationException{
        // Called once when the SOE’s context is shut down
    }

    //IMySoeInterface method
    public String mySoeFoo(){
        return "some string";
    }
}

此批注是必填项，如果没有此批注，则在部署时，SOE的Java类将对ArcGIS for Server不可见。因此，该SOE在运行时将不存在

@ServerObjectExtProperties

SOE需要@ServerObjectExtProperties批注，以保存将SOE部署为地图服务的扩展时提供给ArcGIS Server的名称/值。

支持以下元素对：

• displayName defines the name your SOE will show when users enable it as a capability in an ArcGIS Server administrative client such as ArcGIS Server Manager and ArcGIS Pro. This name can have spaces.
• description is used to describe your SOE in a more detailed and user-friendly manner. It will show up in an ArcGIS Server administrative client to help administrators understand the usage of your SOE.
• properties is where you can define properties on your SOE. For example, if an SOE allows editing of a layer, a property value could dictate which layer would be available for editing, thus giving the administrator control over runtime usage/behavior of the SOE.
• allSOAPCapabilities defines all available capabilities that an SOE can have. When exposing your SOE as a web service, you can create functionality that can be enabled or disabled by an administrator of ArcGIS Server. Such functionality is called a “web capability”. This parameter’s value is a comma-separated list that holds all capabilities exposed by an SOE.
• defaultSOAPCapabilites lists all web capabilities that are enabled on the SOE by default.
• supportsSharedInstances is a boolean parameter defining whether the SOE can be enabled with a service using shared instances. If this property is not present in the SOE, the SOE can't be applied to a service which is set to use shared instances. This property is introduced at 10.8.1 version.

displayName定义您的SOE在用户将其作为ArcGIS Server管理客户端（例如ArcGIS Server Manager和ArcGIS Pro）中的功能启用时将显示的名称。这个名字可以有空格。

description用于以更详细和用户友好的方式描述您的SOE。它将显示在ArcGIS Server管理客户端中，以帮助管理员了解SOE的用法。

properties 是您可以在SOE上定义属性的地方。例如，如果SOE允许编辑层，则属性值可以指示哪个层可用于编辑，从而使管理员可以控制SOE的运行时使用情况/行为。

allSOAPCapabilities定义SOE可以具有的所有可用功能。将SOE作为Web服务公开时，可以创建可由ArcGIS Server管理员启用或禁用的功能。这种功能称为“网络功能”。此参数的值是一个逗号分隔的列表，其中包含SOE公开的所有功能。

defaultSOAPCapabilites列出了默认情况下在SOE上启用的所有Web功能。

supportSharedInstances是一个布尔参数，定义是否可以使用共享实例通过服务启用SOE。如果SOE中不存在此属性，则无法将SOE应用于设置为使用共享实例的服务。此属性是在10.8.1版本中引入的。

以下代码段演示了上述注释和可用属性及其值的用法：

// SOE class
@ArcGISExtension
@ServerObjectExtProperties(displayName = "My SOE", description = "My first SOE",
    properties = {"property1Name=property1Value", "property2Name=property2Value"},
    defaultSOAPCapabilities = {"myWebCapability1"},
    allSOAPCapabilities = {"myWebCapability1", "myWebCapability2"},
    supportsSharedInstances = false)

public class SOE implements IServerObjectExtension, IMySoeInterface{

    public void init(IServerObjectHelper arg0)throws IOException,
        AutomationException{
        // Called once when the instance of the SOE is created
    }

    public void shutdown()throws IOException, AutomationException{
        // Called once when the SOE’s context is shut down
    }

    //IMySoeInterface method
    public String mySoeFoo(){
        return "some string";
    }

}

Interfaces and classes

以下是您的SOE可以实现的一些接口，以启用SOE内部的特定行为。

---

com.esri.arcgis.system.IObjectConstruct

该接口是可选的，仅当SOE需要额外的初始化（例如使用ArcGIS Server管理器中的服务器管理员定义的值初始化属性）时才需要实现。该接口包含一个称为Construct（）的方法，该方法在IServerObjectExtension.init（）被调用之后在创建SOE时仅被调用一次。

---

com.esri.arcgis.system.IObjectActivate

IObjectActivate接口是可选的（也就是说，除非您的SOE需要在处理请求之前和之后执行的特殊逻辑，否则不需要其实现）。它包括两种方法：

• activate() — Called each time a client makes a request to the SOE, via SOAP or REST（客户端每次通过SOAP或REST向SOE请求时调用）
• deactivate() — Called each time a client gets and releases the server object's context.（每当客户端获取并释放服务器对象的上下文时调用。）

---

 com.esri.arcgis.server.SOAPRequestHandler

如果计划将Java SOE作为基于SOAP的Web服务公开，则SOE类必须扩展SOAPRequestHandler基类。如果要创建REST SOE，则不需要扩展此基类。此基类定义了IRequestHandler接口公开的handleStringRequest（）方法。该方法接收SOAP请求，从SOE类调用适当的业务方法，生成SOAP响应，然后将其返回给客户端应用程序，从而减轻了您处理SOAP请求和响应的负担，并使您可以专注于SOE的业务逻辑开发。

---

com.esri.arcgis.system.IRESTRequestHandler

如果计划将Java SOE作为RESTful Web服务公开，则必须实现IRESTRequestHandler接口。该接口提供了两种方法：

• handleRESTRequest() — Called once for each HTTP request to the SOE.（对于对SOE的每个HTTP请求调用一次。）
• getSchema() — Called by the ArcGIS REST handler to interrogate the SOE for its resource and operations hierarchy at runtime.（由ArcGIS REST处理程序调用，以在运行时查询SOE的资源和操作层次结构。）