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()