On this page

This section provides query methods that you can use to retrieve an array of elements by query pattern.

Retrieving an Array of Element by Query Pattern

$query.get(query)
  • Parameters: query : String (the query string as described in section Recognizable Query Patterns.
  • Returns: java.util.List<Element> (a list or a collection of MagicDraw Elements or an empty List if there is no matching element).
  • The sample code to print all Use Case elements under a packagable element named foo is as follows:
#foreach ($uc in $query.get("usecase[owner=foo]")) 
 $uc.name in $uc.owner.name 
#end

Getting a Single Result from Query Functions

Since a MagicDraw model element does not have a unique identified attribute so all methods will be returned in a Collection. Thus we will need convenient methods to get a single result from the Collection.  Additional methods for getting a single result from query methods are as follows:

  • first() – returns the first element from a collection.
  • last() – returns the last element from a collection.
  • get(int) – returns the nth element of a collection.
  • unique() – returns the first element from a collection (equivalent to first).

Getting the First Element from a Collection

$query.get(query).first()
  • Returns: Element (the first element from a query result collection or a null value if there is no matching element).
  • A Sample code to print the first package is as follows:
$query.get("package").first()

Getting the Last Element from a Collection

$query.get(query).last()
  • Returns: Element (the last element from a query result collection or a null value if there is no matching element).
  • A sample code to print the last package is as follows:
$query.get("package").last()

Getting the nth Element from a Collection

$query.get(query).get(index)
  • Parameters: index : int (a zero-based integer indicating which element to retrieve).
  • Returns: Element (an element from a specified index of a query result collection or if the index is out of bounds, it will print a warning message to console/log and returns a null value)
  • A sample code to print the third package is as follows:
$query.get("package").get(2)

Getting the Unique Element from a Collection

$query.get(query).unique()

This method is equivalent to the one in section Getting the First Element from a Collection.

  • Returns: Element (a unique element from a query result collection or a null value if there is no matching element).
  • A sample code to print a single package is as follows:
$query.get("package").unique()

Retrieving an Array of Elements by Name

$query.getElementsByName(name)

Retrieve an element from a selected package scope whose element name exactly equals a given parameter. This method is equivalent to query pattern *[name=var].

  • Parameters: name : String (the element name string).
  • Returns: java.util.List<Element> (a List or a collection of MagicDraw Elements or an empty List if there is no matching element).
  • A sample code to print the first element whose name exactly equals to foo is as follows:
$query.getElementsByName("foo").unique()

Retrieving Elements by ID

$query.getElementById(id)

Retrieve an element from a selected package scope whose element ID exactly equals a given parameter. This method is equivalent to query pattern #id.

  • Parameters: id : String (an element’s ID).
  • Returns: Element (a MagicDraw Element or a null value if there is no matching element).
  • A sample code to print an element that contains ID 17_0_3_8e9027a_1325220298609_477646 is as follows:
$query.getElementById("17_0_3_8e9027a_1325220298609_477646").unique()