With ArcGIS Server 9.3.1 we introduced Server Object Extensions (SOE) in Java. Java SOE's offer developers an opportunity to encapsulate low level GIS functionality in desktop or web applications. In the ArcObjects Java Developer Help System we document two approaches to consuming SOE's in a console application and in a web application. In our web application approach, we document using a Java Server Faces (JSF) managed bean pattern where the business logic, SOE, is applied to a command button component in an action listener. This pattern does not directly depend on the Java Web ADF, but it can be used to extend a Web ADF application. To take advantage of patterns the Java Web ADF offers, we will take a look at extending the Java Web ADF Task Framework to consume a SOE using the Hello World SOE Developer walkthrough.
Creating a Custom Java Web ADF Task that consumes an SOE involves the following steps once you have successfully deployed your SOE:
- Include the SOE jar File in your Web ADF libraries
- Create a Java Task Class to consume the SOE
- Register the Class as a Managed Bean
- Add the task control to the JSP page with a reference to the managed bean
Add SOE Jar File
Copy the HelloWorldSOE jar file into the WEB-INF\lib folder of your Web ADF application so that you have local access to the SOE business object in your WEB ADF application.
Create a Java Class to consume the SOE
To work with our HelloWorld SOE, you will want to create a command, or action, task and send the return to the Results panel. Commands allow you to execute business logic in your SOE without any user interaction with the map. To create a Web ADF Task, you can either manually create a Java class file and associated TaskInfo classes or use a supported developer IDE like Eclipse to stub out all your Task Class artifacts. Once you have your Task Class created, implement the following method:
[Java]
public void getMessage(TaskEvent event){
System.out.println(this.getClass().getName() + ":getMessage()");
try{
// Get a handle to the Local ArcGIS Service
AGSLocalMapResource resource = (AGSLocalMapResource)event.getWebContext()
.getResources().get("ags1");
// Get a handle to the SOE
IServerObject so = resource.getServerContext().getServerObject();
IServerObjectExtension soe = ((IServerObjectExtensionManager)so)
.findExtensionByTypeName("HelloWorldSOE");
IHelloWorldSOE hwSoe = (IHelloWorldSOE)soe;
// Invoke the HelloWorld SOE
String soeReturn = hwSoe.helloWorld();
// Add attributes to a list to send to WebResults
List < String > values = new ArrayList < String > ();
String id = "" + System.currentTimeMillis();
values.add(id); // Unique identifier
values.add(soeReturn); // SOE Message
// Add a List of results to the WebResults object
WebContext context = event.getWebContext();
WebResults results = context.getWebResults();
results.addResults("SOE Message", values);
}
catch (Exception e){
e.printStackTrace();
}
Let's explain the method code above. First we need to get a handle to the Map Service which the SOE is enabled on. In the WebADF, we can get this from the named resource in our faces-config file. In our case the resource is named 'ags1' and we use a Local Connection to cast to. Once we have the Map Service, we can get access to the associated Server Object and we can gain access to extensions with the method findExtensionbyTypeName( <soename> ). The return object from this method call can be collected by IServerObjectExtension and this reference can be used to call a method on the SOE. At this point in our simple example, we just want to display the return from our SOE in our application. We can easily use the WebADF Results Panel to post the return message. The WebResults object is maintained by the WebContext and can be accessed via the WebContext.getWebResults() method. The result objects that you add to WebResults can provide up to 4 types of information. We will use the addResults() method to add a Results Header and the result data supplied as a java.util.List object. That is all the code required to access our SOE and send the response to the Results Panel. We take advantage of the simplicity of both the SOE and the Web ADF Framework in this pattern.
Register the Class as a Managed Bean
When your Task code is complete, you need to register it as a managed bean. If you used a supported developer IDE, the Task template process created these entries for you. If not, you can manually do this by opening the faces-config.xml file from your WEB-INF folder and scroll down toward the end of the file and append the following tag content below the last managed bean.
[XML]
<managed-bean>
<managed-bean-name>helloWorldSvc</managed-bean-name>
<managed-bean-class>sample.soe.task.HelloWorldSvc</managed-bean-class>
<managed-bean-scope>none</managed-bean-scope>
</managed-bean>
And add the following as a map-entry under the root mapContext managed bean:
[XML]
<map-entry>
<key>helloWorldSvc</key>
<value>#{helloWorldSvc}</value>
</map-entry>
Add the task control to the JSP page with a reference to the managed bean
The final step in the process is to add the task control and link to your jsp page. Open your mapviewer.jsp file and add the new task control to the list of tasks in your application. The task tags are typically toward the bottom of the mapviewer.jsp file in the WMA. Note, our task control assumes an associated TaskInfo class was created and links it appropriately here.
[HTML]
<!-- New SOE Task Tag in the JSP File -->
<a:task id="helloWorldTask" value="#{mapContext.attributes.helloWorldSvc}" taskInfo="#{mapContext.attributes.helloWorldSvc.taskInfo}" mapId="map1" />
Now add a task link to the 'task-menu'. In your WMA mapviewer.jsp file you will see this <div> tag content holding the applications Search Attributes task.
[HTML]
<li class="menu-bar">
<a
href="#"
class="menu-header"
title="SOE Task"
onclick="toggleWindow('win_EsriTaskCell_helloWorldTask');">
<span>
Hello World SOE
</span>
</a>
</li>
Run your application
You nave now completed the steps to implement your custom task which consumes the HelloWorld SOE. You can now deploy and run your application to see it work. Once the application loads, you should see your 'Hello World SOE' link at the top of the Task Menu bar. When executed the results are sent to the Results Panel as shown below:
The Web ADF Task framework offers vast flexibility for you to consume SOE's in your web application. The framework provides a mechanism that lets you focus on working with SOE's instead of being concerned with low level implementations in your web application.