SubmitOperationAgent verifies that attributes are valid. More...

#include <SubmitOperationAgent.h>

Inheritance diagram for smtk::task::SubmitOperationAgent:

Collaboration diagram for smtk::task::SubmitOperationAgent:

Classes
struct	ParameterSpec
	Per-parameter configuration of item values. More...

struct	ParameterSpecRef
	A reference to a ParameterSpec within m_parameters. More...

Public Types
enum	RunStyle { Iteratively, Once, OnCompletion }
	Specify how users interact with the operation. More...

enum	ConfiguredBy { ConfiguredBy::Static, ConfiguredBy::Port, ConfiguredBy::User }
	Specify what is allowed to configure an operation parameter. More...

enum	ItemVisibility { ItemVisibility::Off, ItemVisibility::RecursiveOff, ItemVisibility::On }
	Specify whether an item and its children should be visible to users. More...

enum	PortDataHandler { PortDataHandler::AddObjects, PortDataHandler::SetObjects, PortDataHandler::AssignFromAttribute, PortDataHandler::AssignFromAttributeResource, PortDataHandler::AssignMatchingAttributes }
	Methods for configuring operation parameters mentioned in port-data. More...

using	State = smtk::task::State

using	Configuration = nlohmann::json

using	ParameterSpecMap = std::unordered_map< smtk::string::Token, std::unordered_map< smtk::string::Token, std::vector< ParameterSpec > >>
	All of the ways the operation accepts port-data into its configuration. More...

using	ParameterWatchMap = std::unordered_map< smtk::common::UUID, std::set< ParameterSpecRef > >
	A set of component UUIDs that provide values to be mapped into parameters. More...

using	ObjectSet = std::unordered_set< smtk::resource::PersistentObject * >
	A set of objects from which to assign values.

using	ParameterUpdateMap = std::map< ParameterSpecRef, ObjectSet >
	Used internally to gather objects contributing to the same parameter.

Public Types inherited from smtk::task::Agent
enum	CategoryEvaluation { CategoryEvaluation::Pass, CategoryEvaluation::Reject, CategoryEvaluation::Neutral }
	The set of values that an agent's acceptChildCategories method can return. More...

using	State = smtk::task::State

using	Configuration = nlohmann::json

Public Member Functions
	smtkSuperclassMacro (smtk::task::Agent)

	smtkTypeMacro (smtk::task::SubmitOperationAgent)

	SubmitOperationAgent (Task *owningTask)

State	state () const override
	Return the current state of the agent. More...

void	configure (const Configuration &config) override
	Configure the agent based on a provided JSON configuration.

Configuration	configuration () const override
	Return the agent's current configuration.

std::string	troubleshoot () const override
	Return user-presentable troubleshooting information.

std::shared_ptr< PortData >	portData (const Port *port) const override
	Return port data provided by the agent. More...

void	portDataUpdated (const Port *port) override
	Tell the agent that the data on port has been updated.

smtk::operation::Operation *	operation () const
	Return the operation this task requires users to configure and submit.

RunStyle	runStyle () const
	Return the manner in which this task expects users to submit the operation.

ParameterSpec &	associationSpec ()
	Return the specification for the associations of the operation this task configures. More...

ParameterSpec	associationSpec () const

const ParameterSpecMap &	parameterSpecs () const
	Return the list of operation parameters to copy from an input attribute resource. More...

void	configureHiddenItems (smtk::view::ConfigurationPtr view, const nlohmann::json &jItemArray) const
	Modify view to hide items specified in task's style.

bool	runSinceEdited () const
	True if the operation has successfully run since its parameters were last edited.

bool	setNeedsToRun ()
	Force the task into an incomplete state because its input parameters have changed. More...

Public Member Functions inherited from smtk::task::Agent
	smtkTypeMacroBase (smtk::task::Agent)

	Agent (Task *owningTask)

Task *	parent () const
	Return the agent's parent task.

virtual bool	getViewData (smtk::common::TypeContainer &configuration) const
	Insert view-related objects into configuration. More...

smtk::string::Token	name () const
	Agents may have a name that can be used to distinguish them. More...

virtual CategoryEvaluation	acceptsChildCategories (const std::set< std::string > &cats) const
	Evaluates a set of categories that are associated with potential children tasks.

Static Public Member Functions
static smtk::string::Token	ConfiguredByToken (ConfiguredBy value)
	Convert to/from a ConfigureBy enumerant.

static ConfiguredBy	ConfiguredByValue (smtk::string::Token token)

static smtk::string::Token	ItemVisibilityToken (ItemVisibility value)
	Convert to/from an ItemVisibility enumerant.

static ItemVisibility	ItemVisibilityValue (smtk::string::Token token)

static smtk::string::Token	RunStyleToken (RunStyle value)
	Convert to/from a RunStyle enumerant.

static RunStyle	RunStyleValue (smtk::string::Token token)

static smtk::string::Token	PortDataHandlerToken (PortDataHandler value)
	Convert to/from a PortDataHandler enumerant.

static PortDataHandler	PortDataHandlerValue (smtk::string::Token token)

Protected Member Functions
void	taskStateChanged (State prev, State &next) override
	Receive notification the parent Task's state has changed.

void	taskStateChanged (Task *task, State prev, State next) override
	Receive notification that a Task's state has changed. More...

int	update (const smtk::operation::Operation &op, smtk::operation::EventType event, smtk::operation::Operation::Result result)
	Respond to operations that may change task state.

bool	prepareParameterUpdates (ParameterUpdateMap &parametersToUpdate, const std::shared_ptr< smtk::attribute::ComponentItem > &components, bool expunging, bool &requireStateCheck)
	Insert objects that should be mapped to operation parameters into parametersToUpdate. More...

bool	copyToParameters (ParameterUpdateMap &parametersToUpdate)
	Invoke copyToParameter on each entry of parametersToUpdate. More...

bool	copyToParameter (const ParameterSpecRef &ref, const std::unordered_set< smtk::resource::PersistentObject * > &objects)
	Copy values from objects into the referenced parameter (ref ). More...

bool	copyToIntParameter (const ParameterSpec &spec, smtk::attribute::IntItem *targetInt, const ObjectSet &objects)
	Copy values from objects into targetInt.

bool	copyToDoubleParameter (const ParameterSpec &spec, smtk::attribute::DoubleItem *targetDouble, const ObjectSet &objects)
	Copy values from objects into targetDouble.

bool	copyToStringParameter (const ParameterSpec &spec, smtk::attribute::StringItem *targetString, const ObjectSet &objects)
	Copy values from objects into targetString.

bool	copyToReferenceParameter (const ParameterSpec &spec, smtk::attribute::ReferenceItem *targetReference, const ObjectSet &objects)
	Copy values from objects into targetReference.

virtual State	computeInternalState ()
	Check m_resourcesByRole to see if all requirements are met.

Protected Attributes
ParameterSpecMap	m_parameterSpecs

ParameterWatchMap	m_watching

State	m_internalState { State::Unavailable }

smtk::common::Managers::Ptr	m_managers

smtk::operation::Observers::Key	m_observer

ParameterSpec	m_associationSpec

RunStyle	m_runStyle { RunStyle::Iteratively }

bool	m_runSinceEdited { false }

std::shared_ptr< smtk::operation::Operation >	m_operation

smtk::string::Token	m_outputPortName
	Allow users to name a port+role where this agent produces a set of resources reported as created/modified/expunged by the agent's most recent execution of its operation. More...

smtk::string::Token	m_outputRole

std::set< std::weak_ptr< smtk::resource::Resource >, std::owner_less< std::weak_ptr< smtk::resource::Resource > > >	m_outputResources

Protected Attributes inherited from smtk::task::Agent
smtk::task::Task *	m_parent

smtk::string::Token	m_name
	A name that can be used to distinguish instances of agents.

Detailed Description

SubmitOperationAgent verifies that attributes are valid.

Member Typedef Documentation

◆ ParameterSpecMap

using smtk::task::SubmitOperationAgent::ParameterSpecMap = std::unordered_map< smtk::string::Token, std::unordered_map<smtk::string::Token, std::vector<ParameterSpec> >>

All of the ways the operation accepts port-data into its configuration.

This specifies how port-data should be ingested. When matching port-data is detected (during portDataUpdated()), then entries are added to the ParameterWatchMap.

◆ ParameterWatchMap

using smtk::task::SubmitOperationAgent::ParameterWatchMap = std::unordered_map<smtk::common::UUID, std::set<ParameterSpecRef> >

A set of component UUIDs that provide values to be mapped into parameters.

This is used by the operation observer to update the operation's configuration.

Member Enumeration Documentation

◆ ConfiguredBy

enum smtk::task::SubmitOperationAgent::ConfiguredBy

strong

Specify what is allowed to configure an operation parameter.

Note that this enumeration does not include a value for specifying that an item may only be configured by a user. For that behavior, simply omit the item's path from the task configuration.

Enumerator
Static	Static agent configuration (not port data) provides values.
Port	Port data is allowed to modify the parameter whenever updated.
User	Tasks, ports, and the user are allowed to edit the parameter.

◆ ItemVisibility

enum smtk::task::SubmitOperationAgent::ItemVisibility

strong

Specify whether an item and its children should be visible to users.

Enumerator
Off	Hide this item but not its children.
RecursiveOff	Recursively hide this item and its children.
On	Show this item and its children.

◆ PortDataHandler

enum smtk::task::SubmitOperationAgent::PortDataHandler

strong

Methods for configuring operation parameters mentioned in port-data.

Enumerator
AddObjects	Append objects to an operation parameter/associations. If a component is subsequently expunged from a resource or a resource is released from its manager, it will be removed from the operation's parameters.
SetObjects	Reset an operation parameter/association to the objects present. If a component is subsequently expunged from a resource or a resource is released from its manager, it will be removed from the operation's parameters.
AssignFromAttribute	Assign an attribute's item to an operation-parameter's item. If the source item is subsequently modified, the operation will be updated to match the new values.
AssignFromAttributeResource	Find matching attributes in a resource and assign one of its items to an operation-parameter's item. If the source item is subsequently modified, the operation will be updated to match the new values.
AssignMatchingAttributes	Accept any attribute (either as a lone object or inside an attribute resource) that matches the specification, assigning one of its items to an operation-parameter's item. This is identical to the combination of AssignFromAttribute and AssignFromAttributeResource. If the source item is subsequently modified, the operation will be updated to match the new values.

◆ RunStyle

enum smtk::task::SubmitOperationAgent::RunStyle

Specify how users interact with the operation.

Enumerator
Iteratively	Users edit parameters and run the operation, possibly repeatedly.
Once	Users run the operation once (at which point the task is marked complete).
OnCompletion	Users do not run the operation; the task launches it when marked complete.

Member Function Documentation

◆ associationSpec()

ParameterSpec& smtk::task::SubmitOperationAgent::associationSpec ( )

inline

Return the specification for the associations of the operation this task configures.

Note that if the operation is not intended to auto-configure the associations, the m_itemPath member of the parameters should be set to "-ignore-" (rather than empty or populated with the name of the association's ReferenceItem).

◆ copyToParameter()

bool smtk::task::SubmitOperationAgent::copyToParameter	(	const ParameterSpecRef &	ref,
		const std::unordered_set< smtk::resource::PersistentObject * > &	objects
	)

protected

Copy values from objects into the referenced parameter (ref ).

This returns true if any parameters were modified.

◆ copyToParameters()

bool smtk::task::SubmitOperationAgent::copyToParameters ( ParameterUpdateMap & parametersToUpdate )

protected

Invoke copyToParameter on each entry of parametersToUpdate.

In the future, this may fetch other objects from which parameter values should be drawn (when there is a need to combine values from multiple objects to set a single operation-parameter's value).

◆ parameterSpecs()

const ParameterSpecMap& smtk::task::SubmitOperationAgent::parameterSpecs ( ) const

inline

Return the list of operation parameters to copy from an input attribute resource.

The input attribute resource is expected to be provided via an input port.

◆ portData()

std::shared_ptr< PortData > smtk::task::SubmitOperationAgent::portData ( const Port * port ) const

overridevirtual

Return port data provided by the agent.

If the agent is not assigned to port, the method returns nullptr.

Reimplemented from smtk::task::Agent.

◆ prepareParameterUpdates()

bool smtk::task::SubmitOperationAgent::prepareParameterUpdates	(	ParameterUpdateMap &	parametersToUpdate,
		const std::shared_ptr< smtk::attribute::ComponentItem > &	components,
		bool	expunging,
		bool &	requireStateCheck
	)

protected

Insert objects that should be mapped to operation parameters into parametersToUpdate.

The ComponentItem passed should be from an operation result's report of created, modified, or expunged components.

This returns true if any entries were added to parametersToUpdate.

◆ setNeedsToRun()

bool smtk::task::SubmitOperationAgent::setNeedsToRun ( )

Force the task into an incomplete state because its input parameters have changed.

This is invoked by configureHiddenItems() if any items are modified. The returned value is true if the call had any effect (i.e., m_runSinceEdited was true before the call and false afterward).

Calling this method will generally result in a state change (to Incomplete) if true is returned.

◆ state()

State smtk::task::SubmitOperationAgent::state ( ) const

inlineoverridevirtual

Return the current state of the agent.

This is Unavailable when no resources/attributes/definitions have been configured for validation; it is Incomplete when at least one attribute is configured for validation but is not in a valid state; and Completable when all the configured attributes are valid.

Implements smtk::task::Agent.

◆ taskStateChanged()

void smtk::task::SubmitOperationAgent::taskStateChanged	(	Task *	task,
		State	prev,
		State	next
	)

overrideprotectedvirtual

Receive notification that a Task's state has changed.

This method would allow a Task to delegate children state calculation to an SubmitOperationAgent instead

Reimplemented from smtk::task::Agent.

Member Data Documentation

◆ m_outputPortName

smtk::string::Token smtk::task::SubmitOperationAgent::m_outputPortName

protected

Allow users to name a port+role where this agent produces a set of resources reported as created/modified/expunged by the agent's most recent execution of its operation.

These member variables are assigned by configure() and, if m_outputPortName is invalid, are ignored.

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

/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/task/SubmitOperationAgent.h
/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/task/SubmitOperationAgent.cxx

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ ParameterSpecMap

◆ ParameterWatchMap

Member Enumeration Documentation

◆ ConfiguredBy

◆ ItemVisibility

◆ PortDataHandler

◆ RunStyle

Member Function Documentation

◆ associationSpec()

◆ copyToParameter()

◆ copyToParameters()

◆ parameterSpecs()

◆ portData()

◆ prepareParameterUpdates()

◆ setNeedsToRun()

◆ state()

◆ taskStateChanged()

Member Data Documentation

◆ m_outputPortName