Working with Resources

Transcription

1 Autodesk MapGuide Enterprise Working with Resources Autodesk MapGuide Enterprise software has a powerful API (application programming interface) for manipulating resources such as feature and drawing sources, maps, layers, and layouts. Using the Resource Service API, MapGuide-based applications can perform operations such as dynamic theming, data filtering, and layer creation among others, providing a rich, interactive experience for your users. This paper provides an in-depth look at resources and the resource service API in Autodesk MapGuide Enterprise. The information in this paper is applicable to both the MapGuide Open Source and Autodesk MapGuide Enterprise versions of the platform.

2 Contents Introduction...3 Resources and the Resource Database...4 Resource Identifiers...5 Resource Service API...5 Layer Definition Resource XML Schema...7 Using Templates to Make Dynamic Resource Creation Easy...11 Modifying Resource XML Documents with the DOM...12 Computing Distributions with the MgFeatureService SelectAggregate API...13 Putting It Together in the Theme Task...14 Resources...16 Appendix A: Sample Layer Definition for the Parcel Layer in Figure

3 Introduction Resources are XML documents that define feature sources, drawing sources, layers, maps, and the user interface (layout) of the Autodesk MapGuide Viewer. This paper introduces the concepts and demonstrates how to create and modify resources on a peruser basis in MapGuide applications. This can be useful if your application needs to dynamically add layers, change layer filters or stylization, or customize the map or web layout based on who the user is. The code samples in the paper were taken from a sample application that is available on the Autodesk MapGuide Technology Resource Center website ( learnmapguide or data.mapguide.com/mapguide/gt/index.php for the direct link to the sample and source code download). The Theme task in the sample application allows the end user to theme or retheme a polygon layer (Figure 1). Figure 1: Sample Application Theme Task Users start by selecting a layer to theme and a property to use for the theme value. From there they can choose a statistical distribution from a drop-down menu that includes all the standard commands offered in Autodesk MapGuide Studio (Individual, Equal, Standard Deviation, Quantile, and Jenks [Natural Breaks]) and the number of rules/categories to create. For the style ramp they can choose the starting and ending fill and border colors. Once they have made their choices, clicking Apply creates a new layer (using all the properties of the selected layer) and inserts it in the map just above the existing layer in the draw order. 3

4 This paper covers all of the Autodesk MapGuide APIs and techniques used to create the theme application. Resources and the Resource Database Autodesk MapGuide Enterprise stores map definitions, layer definitions, data source connections, symbol definitions, and web and print layouts as XML documents in the Resource Database. These XML documents are referred to as resources. Resources are stored within the Resource Database in a directory-like hierarchy. Each stored resource has two fundamental parts: a header and content. The content is the XML document itself, such as the content of a file in the file system. The header is also an XML document that defines access permissions and metadata for the resource. Continuing the file system analogy, resources are also typed, that is, you can immediately distinguish between a map definition and a layer definition without reading and examining the content. All resource XML is defined by a W3C XML schema, and by default documents are validated against the schema when they are written to the resource database. Resource documents can refer to other resources and can have associated data, such as files, strings, or streams of bytes. Figure 2 shows the various resource types supported by Autodesk MapGuide Enterprise and which ones typically contain references to other resources, use resource data, or both. Resources References another resource Uses resource data Web Layout Print Layout [1] The specific requirements for Data File, Configuration Document, and Credentials data for a given Feature Source depends on the FDO Provider. [2] Session based Map resources do not have XML document content, they are stored only as stream based resource data. Map Definition Resource Data Files Streams Strings Layer Definition Symbol Library Symbols Feature Source Definition[1] Data File(s) Drawing Source Definition Configuration Document Credentials Load Procedure DWF File Folder Map[2] Map Feature Set Figure 2: Resource Types, References, and Data Usage The resource database is divided into two separate storage containers called repositories. The library repository is shared by all users and stores resource documents for an indefinite period of time. The Autodesk MapGuide Studio application allows you to create, edit, and manage resources in the library repository. The session repository stores 4

5 transient resources that exist only for the lifetime of a client session. A unique session repository is created for each client session and only that client may access it. When the client session is terminated, that session s repository is deleted along with all of its content. Resource Identifiers A resource identifier specifies the location and type of a resource or folder. Resource identifiers are defined by a URI, such as a string that has the following format: RepositoryType:[RepositoryName]//[ResourcePath/][Resourc ename.resourcetype] The portions in brackets [] are optional. So, for example, the resource identifier for a layer definition called MyLayer within a folder called MyStuff in the library repository would look as follows: Library://MyStuff/MyLayer.LayerDefinition Note there is only one library repository, hence RepositoryName is not applicable. Likewise, to access a layer definition called TempLayer at the root of the user s session, repository would look as follows: Session:{SessionId}//TempLayer.LayerDefinition Note that {SessionId} needs to be replaced by the client s unique session identifier. Finally, to specify a folder resource, use the following syntax: Library://MyFolder/ Note that the trailing slash is required. Resource Service API The MapGuide Resource Service API gives application developers full read/write access to the resource database. Using the methods of the MgResourceService class, your applications can enumerate the resources in the library repository, and read and write resource documents and data in either the library or session repositories. The key MgResourceService methods used in the theme application are GetResourceContent and SetResource, which are used to read the definition of the layer the user wants to theme and subsequently write the updated version to the user s session repository. The signatures of those methods are defined as follows: MgByteReader GetResourceContent(MgResourceIdentifier resource); void SetResource( MgResourceIdentifier resource, MgByteReader content, MgByteReader header); The first method GetResourceContent retrieves the XML content for a specified resource. The second method writes the content and header for a specified resource. If the resource 5

6 does not exist, it is created, and if it already exists, it is updated with the new content and header. For SetResource the following applies: If content and header are both null, the resource being created must be a folder. If header is null and the resource does not yet exist, the security attributes of the parent folder are applied to the resource. If the resource already exists, the header remains unchanged. If content is null, the resource, must exist and the existing header is replaced with the specified one. Using these methods, you can read a layer definition resource as follows: $resid = new MgResourceIdentifier( Library://MyLayer.LayerDefinition ); $bytereader = $resourceservice->getresourcecontent($resid); $layerxml = $bytereader->tostring(); Subsequently writing the LayerDefinition resource to the current session can be accomplished as follows: $resid = new MgResourceIdentifier( Session:. $currsessionid. //MyLayer.LayerDefinition ); $bytesource = new MgByteSource($layerXML, strlen($layerxml)); $resourceservice->setresource($resid, $bytesource->getreader(), null); Using the Byte Reader All service APIs execute methods over a TCP/IP connection to the server. MapGuide streams content over this pipe using the MgByteReader class. $stringdata = $bytereader->tostring(); To create an MgByteReader, you need to use an MgByteSource. $bytesource = new MgByteSource($stringData, strlen($stringdata)); $bytereader = $bytesource->getreader(); In addition to strings, a data file can be used as a source of data for a reader. Now that you know how to read and write resource documents, the next section takes a detailed look at the structure of one of these XML documents, the LayerDefinition. 6

7 Layer Definition Resource XML Schema Arguably one of the most important and most complex resource document types in Autodesk MapGuide Enterprise is the Layer Definition. However, once you understand its structure, you can create dynamic mapping applications. The root element LayerDefinition and its children are described as follows. The LayerDefinition element can contain a single DrawingLayerDefinition, a VectorLayerDefinition, or GridLayerDefinition. DrawingLayerDefinition is used with Drawing.Sources (for example, DWF content). VectorLayerDefinition is used with Feature Sources for vector-based data. GridLayerDefinition is used with Feature Sources (for example, SDF, SHP, Oracle) for raster-based data. 7

8 The VectorLayerDefinition element specifies the source of the data for the vector layer and the stylization rules to be applied to the data. The required elements ResourceId, FeatureName, and Geometry specify the link to the feature source, the name of the feature class, and the name of the geometry property, respectively. The optional PropertyMapping element defines the properties displayed in the Viewer s property pane when a feature on the layer is selected. The optional Filter, URL, and Tooltip elements specify expressions for their namesake concepts. The stylization for the VectorLayerDefinition element is specified by one or more VectorScaleRange elements. 8

9 Each VectorScaleRange element within a VectorLayerDefinition specifies the stylization for a particular scale range. The scale range is specified by the MinScale and MaxScale elements, while the AreaTypeStyle, LineTypeStyle, and PointTypeStyle elements define the stylization for polygon, line string, and point data respectively. The AreaTypeStyle element within a VectorScaleRange contains one or more AreaRule elements. Each AreaRule element within an AreaTypeStyle specifies the stylization for a subset of the polygon feature data. The exact subset is defined by the optional Filter element. AreaRule elements are processed in order, and the first matching rule is applied (all others are skipped). If a Filter element is not specified, the stylization is applied to all polygon features. The optional Label element specifies how to label the features, and the AreaSymbolization2D element specifies how to draw the features. 9

10 The AreaSymbolization2D element within an AreaRule contains two elements, Fill and Stroke, which specify how to draw the fill and border for the polygon features. The Fill element contains FillPattern, ForegroundColor, and BackgroundColor elements, which specify how to draw the area within polygons. Note that color elements are in ARGB format, where the first two hex values specify the transparency. The Stroke element contains LineStyle, Thickness, Unit, and Color elements that specify how to draw a line. Note that color elements are in ARGB format; however, for lines the Alpha value is ignored. To make this more concrete, Appendix A contains a complete listing of the XML for the Parcels layer that corresponds to the screenshot in Figure 1. 10

11 Resource XML Schemas For reference, the XML schema files for all of the resource document types are installed with the Autodesk MapGuide Server and can be found in the following folders: C:\Program Files\Autodesk\<MapGuideVersion>\Server\Schema or C:\Program Files\MapGuideOpenSource\Server\Schema Generally, the best way to understand the Resource schema structures is to create some resources in Autodesk MapGuide Studio and use the File>Save as XML command to look at the actual XML produced by Studio. Using Templates to Make Dynamic Resource Creation Easy Many MapGuide applications need the ability to create resources (or portions of resources), particularly layers, dynamically. Doing that using XML APIs such as DOM or even building up the XML using string concatenation can be daunting and error prone. A much better approach is to use Autodesk MapGuide Studio to create a resource and save it to disk using the File>Save as XML command. You can then edit the XML file with a text editor and replace element or attribute values that need to be set programmatically with a substitution character. Your application can then load the template file and substitute values in place of the substation characters. So in the dynamic theming scenario, you can use an XML template for <AreaRule> elements that looks as follows: <AreaRule> <LegendLabel>%s</LegendLabel> <Filter>%s</Filter> <AreaSymbolization2D> <Fill> <FillPattern>Solid</FillPattern> <ForegroundColor>%s</ForegroundColor> <BackgroundColor>FF000000</BackgroundColor> </Fill> <Stroke> <LineStyle>Solid</LineStyle> <Thickness>0</Thickness> <Color>%s</Color> <Unit>Inches</Unit> </Stroke> </AreaSymbolization2D> </AreaRule> Note the %s substitution characters used in the <LegendLabel>, <Filter>, <ForegroundColor>, and <Color> elements. With the following two lines of code you can have a fully defined <AreaRule> element ready for insertion into a Layer Definition resource. 11

12 $arearuletemplate = file_get_contents("templates/arearuletemplate.xml"); $arearulexml = sprintf($arearuletemplate, GP_CLASS: Residential, GPCLASS = Residential, FF0000FF, FF ); This technique can be applied to snippets of an XML resource document as shown or to entire resource documents. How much you template depends on the requirements of your application. Modifying Resource XML Documents with the DOM The preceding technique for creating resource documents from templates is great when you want to create an entire resource document, but what if you want to modify an existing one? For this you need to turn to the standard W3C DOM APIs ( Implementations of this API exist in the standard PHP, Java, and.net frameworks. For example, the following code shows how to remove all <AreaRule> elements from the first <VectorScaleRange> element. $layerdefresid = new MgResourceIdentifier( Library://MyLayer.LayerDefinition ); $bytereader = $resourceservice->getresourcecontent($layerdefresid); $doc = DOMDocument::loadXML($byteReader->ToString()); $nodelist = $doc->getelementsbytagname('vectorscalerange'); $vectorscalerangecelement = $nodelist->item(0); $areatypestyle = $vectorscalerangecelement ->getelementsbytagname('areatypestyle')->item(0); $arearulelist = $areatypestyle->getelementsbytagname('arearule'); foreach ($arearulelist as $arearule) { $areatypestyle->removechild($arearule); } Now you can insert your new <AreaRule> element created in the previous section with the following code: $areadoc = DOMDocument::loadXML($areaRuleXML); $areanode = $doc->importnode($areadoc->documentelement, true); $areatypestyle->appendchild($areanode); The key takeaway here is that the DOM API can be used with the templating technique shown in the previous section to greatly simplify dynamic XML resource document modification. 12

13 Computing Distributions with the MgFeatureService SelectAggregate API The final piece of the puzzle for putting the theme application together is computing the distributions for generating the new <AreaRule> elements. This is where a powerful but poorly documented API in the MapGuide Feature Service API comes in. The SelectAggregate API of MgFeatureService allows application developers to perform aggregate calculations on the properties of a feature class. The API itself has the following signature: MgDataReader SelectAggregate ( MgResourceIdentifier resource, sting classname, MgFeatureAggregateOptions options); The first two parameters are the same as those of SelectFeatures, the resource identifier of the feature source and the name of the feature class to operate upon. The last parameter is an instance of MgFeatureAggregateOptions. Using the AddComputedProperty method of MgFeatureAggregateOptions, you can perform the following aggregate operations: Operation Syntax Description Count Count(propertyName) Returns a count of the number of features in the feature class with the specified property. Min Min(propertyName) Returns the minimum value of the specified numeric property. Max Max(propertyName) Returns the maximum value of the specified numeric property. EQUAL_DIST EQUAL_DIST(propertyName, numvalues, minvalue, maxvalue) Computes an equal distribution of numvalues for the specified numeric property between minvalue and maxvalue. STDEV_DIST QUANT_DIST JENK_DIST STDEV _DIST(propertyName, numvalues, minvalue, maxvalue) QUANT _DIST(propertyName, numvalues, minvalue, maxvalue) JENK _DIST(propertyName, numvalues, minvalue, maxvalue) Computes a standard deviation distribution of numvalues for the specified numeric property between minvalue and maxvalue. Computes a quantile distribution of numvalues for the specified numeric property between minvalue and maxvalue. Computes a jenks (natural breaks) distribution of numvalues for the specified numeric property between minvalue and maxvalue. So, for example, using SelectAggregate to compute a Quantile distribution of 5 values from 1 to 100 on the Area property of a Parcels feature class could be accomplished with the following code: 13

14 $resid = new MgResourceIdentifier('Library://MyParcels.FeatureSource'); $options = new MgFeatureAggregateOptions(); $options->addcomputedproperty( 'THEME_VALUE', 'QUANT_DIST("Area", 5, 1, 10)'); $datareader = $featureservice->selectaggregate($resid, 'Parcels', $options); while ($datareader->readnext()) { // Get the value of THEME_VALUE from the reader and do something with it! } $datareader->close(); As you can see, the SelectAggregate API can be used to do all the manual work required to compute the distributions for the theme application. Not only that but it is the same API that is used by Autodesk MapGuide Studio when creating themes, so the results are guaranteed to match the results produced by Studio. Putting It Together in the Theme Task Autodesk MapGuide Enterprise applications typically employ a combination of server-side and client-side logic, where the client-side code is focused on user interaction and the server-side code is focused on geospatial processing. Figure 3 illustrates the typical structure and client/server interaction used by Autodesk MapGuide Enterprise applications. Figure 3: MapGuide Application Interaction The Theme Task is written in PHP and follows this model using AJAX (Asynchronous JavaScript and XML) techniques to prevent reloading the task page as selections are made in the client. The application is made up of the five files shown in Figure 4. 14

15 Figure 4: Theme Task Structure The Theme Task user interface is encapsulated in thememain.php. AJAX requests from the client come into themecontroller.php, which hands off processing to the Theme class (theme.php). The LayerInfo (layerinfo.php) and Property (property.php) classes are used to pass complex data structures to the client using another useful technology called JSON (Java Script Object Notation). The key operations supported by the Theme class are as follows: Operation GetMapLayerNames GetLayerInfo Description Returns a list of all polygon layers in the current map. More specifically, it returns all layers that are based on feature geometry with a geometric type of surface. Unlike the other operations, this one is invoked in thememain.php when the Theme task is initialized. Returns information about the Layer selected in the client, including the properties of the feature class that can be used for theming and the scale ranges at which the layer is rendered. The collection of properties includes the property name, data type, and list of distributions supported for that property. GetPropertyMinMaxCount ApplyTheme Returns the minimum value, maximum value, and count of the Property selected in the client. Applies the theming instructions provided by the client and adds the resulting layer to the map. This method reads the existing layer, strips out the existing AreaRules for the specified scale range, computes the distributions, generates new Area rules, and saves the new layer to the user s session repository. Before returning, it adds this new layer to the map just above the existing layer in the draw order. There are also several private methods in the Theme class that play a supporting role for these primary operations. 15

16 What Is JSON? JSON stands for JavaScript Object Notation. It is a technology for representing JavaScript objects in string form. In other words, it allows you to encode an object into a string and then decode that string back into an object. This process is useful in an AJAX application for passing complex data structures between client and server without having to read and write XML documents. Furthermore, JSON is supported by several higher-order languages and tools, including PHP, Java, and.net. This is especially useful because you can encode an instance of a PHP, Java, or.net data structure into a string on the server side, and decode that string into a JavaScript object on the client side. More information on JSON can be found at Resources Source Code and Sample Application Download The sample application used in this paper is available online at under developer samples or the direct link at Autodesk MapGuide Product Center Get the latest information on all versions of MapGuide, including the free data migration tool from the Autodesk website at. Autodesk MapGuide Discussion Group Here you will find the MapGuide discussion group, which is an excellent resource for sharing and obtaining information from your peers. Visit Autodesk MapGuide Developer Discussion Group The MapGuide developer discussion group is another great resources for development issues. Visit MapGuide Open Source Website (OSGeo.org) This site is the destination for information about MapGuide Open Source. Download the latest release from this site and join the mailing lists at mapguide.osgeo.org. Autodesk DWF Developer Center Find developer tools for the DWF-based viewer, including the DWF Viewer API, which can be used with MapGuide Open Source, at 16

17 Appendix A: Sample Layer Definition for the Parcel Layer in Figure 1 <?xml version="1.0" encoding="utf-8"?> <LayerDefinition xmlns:xsi= xmlns:xsd= xsi:nonamespaceschemalocation="layerdefinition xsd" version="1.0.0"> <VectorLayerDefinition> <ResourceId>Library://Redding/Basemap/Data/Parcels.Featu resource</resourceid> <FeatureName>Schema:Parcels</FeatureName> <FeatureNameType>FeatureClass</FeatureNameType> <Filter>NOT STNAME NULL</Filter> <Geometry>Geometry</Geometry> <ToolTip>concat(APN, concat('\nadr: ', STNAME))</ToolTip> <VectorScaleRange> <MaxScale>25000</MaxScale> <AreaTypeStyle> <AreaRule> <LegendLabel>AREA: </LegendLabel> <Filter>"AREA" >= AND "AREA" < </Filter> <AreaSymbolization2D> <Fill> <FillPattern>Solid</FillPattern> <ForegroundColor>ff00ff00</ForegroundColor> <BackgroundColor>FF000000</BackgroundColor> </Fill> <Stroke> <LineStyle>Solid</LineStyle> <Thickness>0</Thickness> <Color>ff000000</Color> <Unit>Inches</Unit> </Stroke> </AreaSymbolization2D> </AreaRule> <AreaRule> <LegendLabel>AREA: </LegendLabel> <Filter>"AREA" >= AND "AREA" < </Filter> <AreaSymbolization2D> <Fill> <FillPattern>Solid</FillPattern> <ForegroundColor>ff44ee00</ForegroundColor> <BackgroundColor>FF000000</BackgroundColor> </Fill> <Stroke> <LineStyle>Solid</LineStyle> <Thickness>0</Thickness> <Color>ff000000</Color> <Unit>Inches</Unit> </Stroke> </AreaSymbolization2D> </AreaRule> <AreaRule> 17

18 <LegendLabel>AREA: </LegendLabel> <Filter>"AREA" >= AND "AREA" < </Filter> <AreaSymbolization2D> <Fill> <FillPattern>Solid</FillPattern> <ForegroundColor>ff88dd00</ForegroundColor> <BackgroundColor>FF000000</BackgroundColor> </Fill> <Stroke> <LineStyle>Solid</LineStyle> <Thickness>0</Thickness> <Color>ff000000</Color> <Unit>Inches</Unit> </Stroke> </AreaSymbolization2D> </AreaRule> <AreaRule> <LegendLabel>AREA: </LegendLabel> <Filter>"AREA" >= AND "AREA" < </Filter> <AreaSymbolization2D> <Fill> <FillPattern>Solid</FillPattern> <ForegroundColor>ffcccc00</ForegroundColor> <BackgroundColor>FF000000</BackgroundColor> </Fill> <Stroke> <LineStyle>Solid</LineStyle> <Thickness>0</Thickness> <Color>ff000000</Color> <Unit>Inches</Unit> </Stroke> </AreaSymbolization2D> </AreaRule></AreaTypeStyle> </VectorScaleRange> </VectorLayerDefinition> </LayerDefinition> Autodesk and Autodesk MapGuide are registered trademarks or trademarks of Autodesk, Inc., in the USA and/or other countries. OSGeo is a trademark of the Open Source Geospatial Foundation in the USA and/or other countries. All other brand names, product names, or trademarks belong to their respective holders. Autodesk reserves the right to alter product offerings and specifications at any time without notice, and is not responsible for typographical or graphical errors that may appear in this document Autodesk, Inc. All rights reserved. 18