PageLayout REST Server Object Extension

Purpose
This sample is a Server Object Extension that generates an image of the associated map service in PageLayout style (that includes the map and cartographic elements such as Scale Bar, North Arrow and Map Legend), as a REST resource. This resource's representation is a URL in json format that points to the generated image.
 
This SOE based REST resource (also called "root resource") has a sub resource called PrintLayout1024x768, which also has a json representation that is a URL of the map image, but of fixed dimensions - 1024 x 768. However, if users of the root resource wish to access the map's pagelayout view as an image of custom dimensions, they can invoke the getPageLayoutBySize() operation on the root resource and specify width, height and dpi of their choice. This operation also returns URL of the generated map image.
 
Figure 1 below shows schema of this REST SOE using UML Class Diagram notations.

How to use

See How to use ArcGIS samples for help on running the sample.

Data has been provided for your use with this sample. It can be found at <Your ArcGIS Developer Kit Install directory>/Samples/data/mxds/portland.mxd and <Your ArcGIS Developer Kit Install directory>/Samples/data/portland/portland.gdb.
If the sample has associated data, you will find that the sample's zip file includes a "data" folder alongside the language folders. However, you will need to update the sample to point to the location of the data once you have extracted all the files.

PageLayout REST SOE Schema
  1. Figure 1 below shows structure of PageLayout SOE, i.e. its operation and sub resource.
  2. If you follow instructions in this document to deploy this SOE to ArcGIS Server, the root URL of the SOE a REST resource would be http://<serverName>:8399/arcgis/rest/services/portland, with "portland" being the map service name.
  3. URLs in Figure 1 below are relative to the above root URL. For example, the final URL for the root resource would be http://<serverName>:8399/arcgis/rest/services/portland/MapServer/exts/PageLayoutSOE.


    4. Figure 1: PageLayout SOE REST Schema

How to deploy PageLayout SOE to ArcGIS Server?
  1. Copy the PageLayout_RESTExt.jar file that holds this SOE, from the $AGSDEVKITJAVA/java/samples/arcobjects/serverobjectextensions/pagelayout_rest/lib folder to $AGSSERVERJAVA/java/lib/ext folder.
  2. Alternatively, if you open this sample's Eclipse project in Eclipse IDE, you can export the PageLayoutSOE.java file to a jar file and save the jar file to the $AGSSERVERJAVA/java/lib/ext folder.
  3. Log into ArcGIS Manager. Navigate to "Manager Extensions" page in "GIS Server" section.
  4. Refresh this page. If the jar file containing PageLayout SOE indeed exists in $AGSSERVERJAVA/java/lib/ext folder, then ArcGIS Manager will display a record for this SOE on this page.
  5. Click on "Register" link next to the PageLayout SOE.
  6. The PageLayout SOE is now registered as extension to all Map Services.

How to enable PageLayout SOE with particular instance of Map service?
  1. Publish a map document as map service using ArcGIS Manager or ArcCatalog's "Publish GIS Resource" or "Add New Service" wizards.
  2. Create the map service using the "portland.mxd" map document from $AGSDEVKITJAVA/java/samples/data/mxds folder. The PageLayout SOE sample is designed to extend a map service that’s based on this portland map document only. We'll call this map service "portland".
  3. On the "Capabilities" page of "Publish GIS Resource" or "Add New Service" wizards, select the capability that matches with PageLayout SOE. Ensure that the check box next to the capability is checked. If there is no capability that matches with "PageLayout", please check if previous SOE deployment and registration step was executed correctly.
  4. If the SOE has capabilities of its own, please select the appropriate ones.
  5. Complete the publishing process and restart map service if necessary.
  6. Ensure that map service shows PageLayout SOE as a capability after it is started, in ArcCatalog or ArcGIS Manager.

How to access PageLayout REST resource?
  1. Open Services Directory web application (at http://<your server name>:8399/arcgis/rest/services/portland/MapServer)
  2. Scroll down the web page to "Supported Extensions:" section and click "PageLayoutSOE" extension. The PageLayoutSOE web page displays the PageLayout SOE's summary, metadata, and links to its sub resources and operations.
  3. Scroll down to the "Supported Interfaces:" section.
  4. Click "REST". This displays info about the resource in json format.
  5. Navigate back to "PageLayout" web page.
  6. Click "Schema". The "Schema" page displays this resource's schema, i.e. its sub-resources, operations, parameters of each operation and supported output formats.

How to consume PageLayout REST resource's operation?
  1. Navigate back to "PageLayout" web page.
  2. Scroll down to the "Supported Operations: " section on the "PageLayout" page,
  3. Click the "getPageLayoutBySize" link. This will bring up the "getPageLayoutBySize" operation web page which includes a form to provide values for this operations input parameters.
  4. Enter values for width, height and dpi (ex: 1280, 1024 and 72).
  5. Select an output format. In this case, we support only 2 output formats, "json" and "html".
  6. Click on "getPrintLayoutBySize(GET)" or "getPrintLayoutBySize(POST)" button.
  7. If the operation is successful, URL to the map image will be displayed on the webpage.
  8. Copy/paste URL in your browser's address bar and press "Enter". An image of portland map should be displayed in PageLayout style, along with cartographic elements such as Scale Bar, North Arrow, and Map Legend.

How to consume PageLayout resource's sub-resource?
  1. Navigate back to "PageLayout" page.
  2. Scroll down to the "Child Resources: " section.
  3. Click the "PageLayout1024x768" link. This will bring up the "PageLayout1024x768" sub resource web page.
  4. This web will display a URL to an image of portland map.
  5. Copy/paste URL in your browser's address bar and press "Enter". An image of portland map with fixed dimensions (1024x768) should be displayed in PageLayout style, alongwith cartographic elements such as Scale Bar, North Arrow, and Map Legend.

How to disable PageLayout SOE with "portland" Map service?
  1. Use ArcGIS Manager or ArcCatalog to access "portland" map service's properties.
  2. On "Capabilities" page, uncheck the check box next to PageLayoutSOE Capability.
  3. Save the map service and restart it if necessary.
  4. The PageLayout SOE is now disabled on the "portland" map service.

How to un-deploy PageLayout SOE?
  1. Log into ArcGIS Manager. Navigate to "Manager Extensions" page in "GIS Server" section.
  2. Click "UnRegister" link next to PageLayoutSOE.
  3. The PageLayout SOE is now unregistered from ArcGIS Server.
  4. Remove the SOE's jar file from $AGSSERVERJAVA/java/lib/ext folder.


Download the files for Java
soe/PageLayoutSOE.java The Page Layout Java Server Object Extension class



Development licensing Deployment licensing
Server Server