TreeResource Class Reference

Class containing behavior tree resource data. More...

#include <auto_apms_behavior_tree_core/tree/tree_resource.hpp>

Inheritance diagram for TreeResource:

Public Member Functions
	TreeResource (const TreeResourceIdentity &search_identity)
	Assemble a behavior tree resource using a TreeResourceIdentity.
	TreeResource (const std::string &search_identity)
	Assemble a behavior tree resource identified by a string.
	TreeResource (const char *search_identity)
	Assemble a behavior tree resource identified by a string.
bool	hasRootTreeName () const
	Determine if this behavior tree resource specifies a root tree.
std::string	getRootTreeName () const
	Get the name of the root tree of this behavior tree resource.
TreeResourceIdentity	createIdentityForTree (const std::string &tree_name="") const
	Create a valid identity string for a specific behavior tree of this resource.
Public Member Functions inherited from BehaviorResourceTemplate< TreeResourceIdentity >
	BehaviorResourceTemplate (const Identity &search_identity)
	Assemble a behavior resource using a BehaviorResourceIdentity.
	BehaviorResourceTemplate (const std::string &search_identity)
	Assemble a behavior resource identified by a string.
	BehaviorResourceTemplate (const char *search_identity)
	Assemble a behavior tree resource identified by a string.
const Identity &	getIdentity () const
	Get the unique identity for this resource.
const std::string &	getBuildRequest () const
	Get the behavior build request associated with this resource.
const std::string &	getDefaultBuildHandlerName () const
	Get the fully qualified class name of the default build handler associated with this behavior resource.
const std::string &	getEntryPoint () const
	Get the entry point of this behavior resource.
const NodeManifest &	getNodeManifest () const
	Get the node manifest associated with this resource.

Static Public Member Functions
static TreeResource	findByTreeName (const std::string &tree_name, const std::string &package_name="")
	Find an installed behavior tree resource using a specific behavior tree name.
static TreeResource	findByFileStem (const std::string &file_stem, const std::string &package_name="")
	Find an installed behavior tree resource using an XML file stem.
Static Public Member Functions inherited from BehaviorResourceTemplate< TreeResourceIdentity >
static BehaviorResourceTemplate	find (const std::string &behavior_alias, const std::string &package_name="", const std::string &category_name="")
	Find an installed behavior resource using a specific behavior tree name.

Detailed Description

Class containing behavior tree resource data.

Behavior tree resources are registered by calling the CMake macro auto_apms_behavior_tree_register_trees in the CMakeLists.txt of a package. They can be discovered once the corresponding package has been installed to the ROS 2 workspace.

Note

auto_apms_behavior_tree_register_trees replaces auto_apms_behavior_tree_register_behavior when registering behavior trees and the user should only invoke the former. Registering the corresponding behavior resource information is handled fully automatically for tree resources.

TreeResource inherits from BehaviorResource and does not define any additional identity resolution logic. The underlying behavior alias for a tree resource is <tree_file_stem>::<tree_name>, so all identity formats supported by BehaviorResource apply uniformly:

• <category_name>/<package_name>::<tree_file_stem>::<tree_name> — Fully qualified.
• <package_name>::<tree_file_stem>::<tree_name> — Omit category (searched in all categories).
• ::<tree_file_stem>::<tree_name> — Omit both category and package (alias-only search). The leading :: MUST be kept to avoid misinterpreting <tree_file_stem> as <package_name>.

Note

When using identity strings, both <tree_file_stem> and <tree_name> must always be specified as part of the behavior alias. For convenience, the static methods findByTreeName() and findByFileStem() allow searching by just one component without requiring the full alias.

Usage

Given the user has specified a behavior tree named MyBehaviorTree inside the XML file behavior/my_tree_file.xml, the CMake macro auto_apms_behavior_tree_register_trees must be called in the CMakeLists.txt of the parent package (for example my_package) like this:

auto_apms_behavior_tree_register_trees(
    "behavior/my_tree_file.xml"
)

The macro automatically parses the given files and detects the names of the trees inside. In the C++ source code, one may use this resource, after the parent package my_package has been installed, like this:

#include "auto_apms_behavior_tree_core/tree/tree_resource.hpp"
 
using namespace auto_apms_behavior_tree;
 
// For example, use the fully qualified tree resource identity signature
const std::string identity_string = "my_package::my_tree_file::MyBehaviorTree";
 
// You may use the proxy class for a tree resource identity
core::TreeResourceIdentity identity(identity_string);
core::TreeResource resource(identity);
 
// Or instantiate the resource object directly from the corresponding identity string
core::TreeResource resource(identity_string);
 
// The resource object may for example be used with TreeDocument
core::TreeDocument doc;
doc.mergeResource(resource);  // Add "MyBehaviorTree" to the document
 
// This also works, so creating a resource object is not strictly necessary
doc.mergeResource(identity_string)
 
// The simplest approach is this
doc.mergeResource("my_package::my_tree_file::MyBehaviorTree");

See also

BehaviorResource

Definition at line 146 of file tree_resource.hpp.

Constructor & Destructor Documentation

TreeResource() [1/3]

TreeResource

(

const TreeResourceIdentity &

search_identity

)

Assemble a behavior tree resource using a TreeResourceIdentity.

Parameters

search_identity

Tree resource identity object used for searching the corresponding resource.

Exceptions

auto_apms_util::exceptions::ResourceError

if the resource cannot be found using the given identity.

Definition at line 54 of file tree_resource.cpp.

TreeResource() [2/3]

TreeResource

(

const std::string &

search_identity

)

Assemble a behavior tree resource identified by a string.

search_identity must be formatted like <package_name>::<tree_file_stem>::<tree_name>.

Parameters

search_identity

Tree resource identity string used for searching the corresponding resource.

Exceptions

auto_apms_util::exceptions::ResourceIdentityFormatError	if the identity string has wrong format.
auto_apms_util::exceptions::ResourceError	if the resource cannot be found using the given identity string.

Definition at line 95 of file tree_resource.cpp.

TreeResource() [3/3]

TreeResource

(

const char *

search_identity

)

Assemble a behavior tree resource identified by a string.

search_identity must be formatted like <package_name>::<tree_file_stem>::<tree_name>.

Parameters

search_identity

C-style tree resource identity string used for searching the corresponding resource.

Exceptions

auto_apms_util::exceptions::ResourceIdentityFormatError	if the identity string has wrong format.
auto_apms_util::exceptions::ResourceError	if the resource cannot be found using the given identity string.

Definition at line 97 of file tree_resource.cpp.

Member Function Documentation

hasRootTreeName()

bool hasRootTreeName

(

)

const

Determine if this behavior tree resource specifies a root tree.

The name of the root tree is determined as follows:

• If the <tree_name> token was present in the resource identity when this instance was created, this is considered the root tree name.
• Otherwise, the XML of the associated tree document is parsed to determine the root tree.

Returns

true if the root tree of this resource can be determined, false otherwise.

Definition at line 99 of file tree_resource.cpp.

getRootTreeName()

std::string getRootTreeName

(

)

const

Get the name of the root tree of this behavior tree resource.

The name of the root tree is determined as follows:

• If the <tree_name> token was present in the resource identity when this instance was created, this is considered the root tree name.
• Otherwise, the XML of the associated tree document is parsed to determine the root tree.

Returns

Name of this resource's root tree.

Exceptions

auto_apms_util::exceptions::ResourceError

if the name of the root tree cannot be determined.

Definition at line 104 of file tree_resource.cpp.

createIdentityForTree()

TreeResourceIdentity createIdentityForTree

(

const std::string &

tree_name = ""

)

const

Create a valid identity string for a specific behavior tree of this resource.

Parameters

tree_name

Name of one of the trees inside this resource's tree document. If empty, do not refer to a specific behavior tree (identity won't be fully qualified).

Returns

Tree resource identity string.

Definition at line 118 of file tree_resource.cpp.

findByTreeName()

TreeResource findByTreeName ( const std::string & tree_name, const std::string & package_name = "" )

static

Find an installed behavior tree resource using a specific behavior tree name.

This method searches the ament resource index for a tree resource whose <tree_name> component matches tree_name. Unlike the identity-string constructor, this accepts just the tree name without requiring <tree_file_stem>.

Parameters

tree_name	The name of the behavior tree.
package_name	Optional package name to narrow the search. If empty, all packages are searched.

Returns

Corresponding tree resource object.

Exceptions

auto_apms_util::exceptions::ResourceError

if no matching resource is found or if the match is ambiguous.

Definition at line 127 of file tree_resource.cpp.

findByFileStem()

TreeResource findByFileStem ( const std::string & file_stem, const std::string & package_name = "" )

static

Find an installed behavior tree resource using an XML file stem.

This method searches the ament resource index for a tree resource whose <tree_file_stem> component matches file_stem. Unlike the identity-string constructor, this accepts just the file stem without requiring <tree_name>.

Parameters

file_stem	The stem (filename without extension) of the behavior tree XML file.
package_name	Optional package name to narrow the search. If empty, all packages are searched.

Returns

Corresponding tree resource object.

Exceptions

auto_apms_util::exceptions::ResourceError

if no matching resource is found or if the match is ambiguous.

Definition at line 191 of file tree_resource.cpp.

---

The documentation for this class was generated from the following files:

• auto_apms_behavior_tree_core/include/auto_apms_behavior_tree_core/tree/tree_resource.hpp
• auto_apms_behavior_tree_core/src/tree/tree_resource.cpp