Public Member Functions

arm4::ArmApplication Class Reference
[ARM 4.0 Applications]

Represents an instance of an executing application. More...

Inheritance diagram for arm4::ArmApplication:
arm4::ArmInterface arm4::ArmApplicationRemote

List of all members.

Public Member Functions

 ArmApplication (const ArmApplicationDefinition &definition, const std::string &group=NullString, const std::string &instance=NullString, const std::vector< std::string > &contextValues=NullVector)
virtual ~ArmApplication ()
 Destructor stops the application implicitly if not stopped by the application.
const std::string & getGroup () const
const std::string & getInstance () const
const std::string & getContextValue (int32_t index) const
 retrieves a context property value.
const ArmApplicationDefinition & getDefinition () const
int32_t end ()
 indicates that the application instance has halted.

Detailed Description

Represents an instance of an executing application.

It provides an anchor point for associating ArmTransaction objects with the application instance. It has the following attributes, all of which are immutable:

  • Application definition. The metadata common to all instances of this application.
  • Group (optional). A group is a set of application instances that are treated as a group for some aspects of management, such as workload balancing (work could be routed to any instance of the group). The maximum length is 255 characters. The value may be a NullString. A non-NullString value should not contain trailing blank characters or consist of only blank characters.
  • Instance (optional). The instance could be used to distinguish between instances of the same application. ARM does not require that this field be used or that it be unique, though its use is suggested. The maximum length is 255 characters. The value may be NullString. A non-NullString value should not contain trailing blank characters or consist of only blank characters.

  • Context values (optional). The "value" part of (name,value) properties that may vary per application instance. The "name" part is available via getDefinition().getIdentityProperties().getContextName(). The values are position-sensitive - they match the position in the referenced context name array. The context property name at the specified array index must have been set to a non-NullString value when the ArmApplicationDefinition object was created. If the name is NullString or a zero-length string, both the name and value are ignored. If the value is NullString or a zero-length string, the meaning is that there is no value for this instance. Names should not contain trailing blank characters or consist of only blank characters.

    Note that both ArmApplication and ArmTransaction have context values that may be unique for each application and transaction instance, respectively. However, the mechanisms for setting the context values are different. In ArmApplication, they are set in the factory method and are immutable afterwards. In ArmTransaction, they are set at any time and processed each time a ArmTransaction::start() executes.

    The reason for the difference is that ArmApplication objects are not reused. One object is created per application instance. If another instance starts, a new ArmApplication is created. This is a reasonable design pattern because applications are long-lived. In most cases, once an application starts, it continues to execute for a long time, so the cost of creating the ArmApplication object and then garbage collecting it is not significant.

    Transactions, on the other hand, are often very short-lived, with response times that are often measured in milliseconds. Creating a new ArmTransaction object for each transaction instance would result in unacceptable and unnecessary overhead. Instead, an ArmTransaction object is created and then reused over and over. Each executing transaction is represented by the paired ArmTransaction::start()/ArmTransaction::stop() methods. For this reason, context values are set using setter methods.

end() indicates that the application instance has halted. After end() executes, the application instance may not call any other method of the ArmApplication object, it may not use any reference to the ArmApplication object, nor may it call any method of any object created using a reference to the ArmApplication object (e.g., creating an instance of ArmTransaction). Any transactions that are currently in-process [ArmTransaction::start() executed but ArmTransaction::stop() not executed] will be discarded by implicitly executing the ArmTransaction::reset() method. The ARM implementation should protect itself against a poorly behaved application that does not respect the specification.

Author:
ARM Working Group of The Open Group, MyARM GmbH

Constructor & Destructor Documentation

arm4::ArmApplication::ArmApplication ( const ArmApplicationDefinition &  definition,
const std::string &  group = NullString,
const std::string &  instance = NullString,
const std::vector< std::string > &  contextValues = NullVector 
)

Constructs the ArmApplication object to which transaction instances are related.

Parameters:
definition metadata describing the type of the ARM application.
group Name of the group the application belongs to. May be a NullString.
instance Name this application instance is given. May be a NullString.
contextValues An array of strings providing the value parts of (name,value) context properties. May be a NullVector.

Member Function Documentation

int32_t arm4::ArmApplication::end (  ) 

indicates that the application instance has halted.

Note:
See comments in the interface description above.
Returns:
0 on success; otherwise, a non-zero error code is returned (as specified in ArmInterface).
const std::string& arm4::ArmApplication::getContextValue ( int32_t  index  )  const

retrieves a context property value.

Parameters:
index the index into the context properties array.
Returns:
The context value at the specified index, or a NullString.
Note:
See comments in the interface description above.
const ArmApplicationDefinition& arm4::ArmApplication::getDefinition (  )  const
Returns:
the metadata describing this application.
const std::string& arm4::ArmApplication::getGroup (  )  const
Returns:
the group name this application is associated with, or a NullString.
Note:
See comments in the interface description above.
const std::string& arm4::ArmApplication::getInstance (  )  const
Returns:
the instance name attributed to this application, or a NullString.
Note:
See comments in the interface description above.
The documentation for this class was generated from the following file:
MyARM
Documentation generated on Thu May 24 2018 22:24:17. © 2018 by MyARM GmbH