Additional XPath functions for EMF and UML data sets

• getDiagrams( )
• getDiagramImage( , , )
• getDiagramHtmlImage( , , , )
• getXMIID( )
• getXMIType( )
• getURI( )
• resolveURI()
• instanceOf( , )
• oclQuery( , )
• oclEvaluate( , )
• getElementsWithStereotype( , )
• getStereotypePropertyValue( , )

Collection<Diagram> getDiagrams (xpath)

This function takes an XPath expression to one or more UML elements and returns a collection of UML diagrams that the elements contain.

Arguments:

xpath: An XPath expression to one or more UML elements

Result:

A collection of UML diagrams that the specified UML elements contain

Application:

On the Row Mapping page, use the function to generate a collection of UML diagrams.

On the Column Mapping page, use the function to query the collection further (for example, to get the count value for the collection).

The function is available for the UML driver..

Example:

This example returns all diagrams in the model:

     getDiagrams( //*)

Blob getDiagramImage (xpath, [resWidth], [resHeight])

This function takes an XPath expression to a diagram element and returns a blob of diagram image data, subject to a maximum resolution, if specified.

Arguments:

xpath: An XPath expression to a diagram element

resWidth (optional): An int that represents the maximum resolution width in pixels

resHeight (optional): An int that represents the maximum resolution height in pixels

Result:

A blob of diagram image data

Application:

Use this function on the Column Mapping page to set up the image column. You can use the column as input to a dynamic image element. Use the optional maximum resolution parameters to control the memory that is needed to render the diagram image. The lower the resolution, the lower the memory that is required; however, the image quality might be lower too.

You can omit the two optional arguments or assign them a value of -1 to indicate that no maximum resolution is specified for the dimension. To make reports more flexible, expose the resolution values to the user as report parameters, instead of hard-coding them.

The function is available for both UML and EMF drivers if the oda-diagrams plug-in is installed.

Examples:

This example returns the diagram image with no restriction:

     getDiagramImage(.)

This example returns the same results as the preceding example:

     getDiagramImage(., -1, -1)

This example returns the diagram image with a maximum resolution of 800 x 600 pixels:

     getDiagramImage(., 800, 600)

This example returns the diagram image with the resolution that the report user specifies:

     getDiagramImage(., $resWidth, $resHeight)

String getDiagramHtmlImage (xpath, genPath, [tileWidth], [tileHeight])

This function takes an XPath expression to a diagram element and returns a string that represents a snippet of HTML code that renders a tiled diagram image.

Arguments:

xpath: An XPath expression to a diagram element

genPath: A path to a temporary directory on the file system that is used for tile generation

tileWidth (optional): The maximum width of a diagram image tile in pixels

tileHeight (optional): The maximum height of a diagram image tile in pixels

Application:

Use this function on the Column Mapping page to set up the image column. You can use the column as input to a dynamic text (HTML) element. The function renders the diagram image by dividing it into tiles whose size is specified by the optional parameters tileWidth and tileHeight.

You can omit the optional parameters or assign them a value of -1 to indicate the default tile size. The tile image is generated in the specified genPath folder. This folder is not cleared after the function is called, and repeated calls overwrite previous images without warning. Use the tile size to control the maximum memory needed to render a diagram. The smaller the tile size, the lower the memory that is needed; however, the number of tiles is higher.

Use this function only with report output formats such as HTML that do not limit page size.

To make reports more flexible, expose the genPath and tile-size values to the user as report parameters, instead of hard-coding them.

The function is available for both UML and EMF drivers if the oda-diagrams plug-in is installed.

Example:

This example divides the image by using the default tile size:

     getDiagramHtmlImage(., "c:/temp")

This example returns the same result as the preceding example:

     getDiagramHtmlImage(., "c:/temp", -1, -1)

This example divides the image using a tile size of 1000 x 1000 pixels:

     getDiagramHtmlImage(., “c:/temp”, 1000, 1000)

String getXMIID (xpath)

This function takes an XPath expression to an element and returns the XMI ID value of the element.

Arguments

xpath: An XPath expression to an element

Result:

The XMI ID value of an element

Application:

Use this function on the Column Mapping page.

The function is available for both UML and EMF drivers.

Example

getXMIID(.)

String getXMIType (xpath)

This function takes an XPath expression to an element and returns the XMI type value of the element.

Arguments:

xpath: An XPath expression to an element

Result:

The XMI type of the element

Application:

Use this function on the Column Mapping page.

The function is available for both UML and EMF drivers.

Example:

This example returns the XMI type of the current element.

getXMItype(.)

String getURI (xpath)

This function takes an XPath expression that resolves to a single element and returns a string representation of the URI of that element. The URI is unique across resources, which makes it an appropriate column to use for joining data sets.

Arguments:

xpath: An XPath expression to a single element

Result:

The URI string of the element

Application:

Use this function on the Column Mapping page.

The function is available for both UML and EMF drivers.

Example:

This example returns a string that represents the URI of the current element:

     getURI(.)

EObject resolveURI (uri)

This function resolves a specified URI and returns the corresponding element.

Arguments:

uri: The URI of an element

Result:

The element with the specified URI

Application:

Use this function on the Row Mapping page or the Column Mapping page.

The function is available for both UML and EMF drivers.

Example:

This example resolves the URI of an element that is passed as a data set parameter.

     resolveURI($element)

Note:

When you use the resolveURI function, consider clearing the check box for Evaluate for every data source instance model in the Row Mapping page. The decision depends on the navigation in the expression:

• If the expression includes navigation that starts from the model root, do not clear the check box. If you clear the check box in this instance, navigation from the root fails and exceptions occur.
• Under other circumstances, clear the check box.

  Typically, the row mapping query in a data set is executed in a loop on the instance models that are defined in the data source that is bound to the data set. In other words, the query execution loops on instance models and for each model, it changes the context of the query to that model and collects the resulting row objects. However, with the resolveURI function, a row mapping query could instead use an object parameter as a context to the query, as in the example resolveURI($class)/ownedAttribute. In such a query, there is no navigation from the root of the model as in typical queries. This means that the result of executing such a query is the same regardless of the context model. This can lead to performance problems because the query is executed again and again for every instance model while the result set does not change.

Collection<EObject> instanceOf (xpath, type)

This function takes an XPath expression and a type string and returns a collection of all elements of that type that are found.

Arguments:

xpath: An XPath expression to one or more elements

type: A string with the format (packagePrefix:typeName) that represents a qualified metatype

Result:

A sub-collection of elements that conform to the specified type

Application:

Use this function on the Row Mapping page or the Column Mapping page.

On the Column Mapping page, use the function to return a collection of elements, and then use additional XPath expressions (for example, count) to query a simple value.

The function is available for both UML and EMF drivers.

Example:

This example returns all elements of type uml:Class:

     instanceOf(//*, "uml:Class")

Collection<EObject> oclQuery (xpath, boolean_ocl_expression)

This function takes an XPath expression and a Boolean-valued OCL query expression, and returns the subset of elements from the XPath expression for which the OCL query returns true.

Arguments:

xpath: An XPath expression

boolean_ocl_expression: A Boolean OCL query string

Result:

A sub-collection of elements that conform to the specified type

Application:

Use this function on the Row Mapping page or Column Mapping page.

On the Column Mapping page, use the function to return a collection of elements, and then use additional XPath expressions (for example, count) to query a simple value.

The function is available for both UML and EMF drivers.

Example:

This example returns all the elements of type uml::Dependency:

     oclQuery(//*, "self.oclIsKindOf(uml::Dependency)")

Object oclEvaluate (xpath , ocl_expression)

This function takes an XPath expression to a single element and an OCL query string, and returns the result after evaluating the query on the element.

Arguments:

xpath: An XPath expression to a single element

ocl_expression: An OCL query string

Result:

The result of evaluating the OCL expression on the specified element

Application:

Use this function on the Row Mapping page or the Column Mapping page to evaluate OCL expressions on elements.

The function is available for both UML and EMF drivers.

Examples:

This example returns all the nested packages in a model (Row Mapping page):

     oclEvaluate(Model, ”self.nestedPackages”)

This example returns the element name (Column Mapping page):

     oclEvaluate(., "name")

Collection<Element> getElementsWithStereotype (xpath, stereotype)

This function takes an XPath expression to one or more UML elements and a stereotype, and returns a collection of elements with the given stereotype.

Arguments:

xpath: An XPath expression to one or more UML elements

stereotype: The fully qualified name of a stereotype with the format (profileName::stereotypeName)

Result:

A sub-collection of elements to which the specified stereotype is applied

Application:

Use this function on the Row Mapping page or the Column Mapping page.

On the Column Mapping page, use the function to get the collection of elements, and then use additional XPath expressions (for example, count) to query a simple value.

The function is available only for the UML driver.

Example:

This example returns all the elements in the model that are stereotyped as business goals:

          getElementsWithSterotype(//*, "Business Modeling::BusinessGoal")

Object getStereotypePropertyValue (xpath, property)

This function takes an XPath expression to a single UML element and a stereotype property, and returns the value of the given stereotype property.

Arguments:

xpath: An XPath expression to a single UML element

property: The: fully qualified name of a stereotype property with the format (profileName::stereotypeName::propertyName)

Application:

Use this function on the Row Mapping page or the Column Mapping page.

The function is available only for the UML driver.

Example:

This example returns the enumeration literal that represents the kind of the business rule that the period denotes:

     getStereotypePropertyValue( . , "Business Modeling::BusinessRule::Kind")