Public Member Functions

arm4::QArmApplication Class Reference
[ARM 4.0 Applications]

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

Inheritance diagram for arm4::QArmApplication:
arm4::QArmInterface arm4::QArmApplicationRemote

List of all members.

Public Member Functions

 QArmApplication (const QArmApplicationDefinition &definition, const QString &group=NullString, const QString &instance=NullString, const QVector< QString > &contextValues=NullVector)
virtual ~QArmApplication ()
 Destructor stops the application implicitly if not stopped by the application.
const QString & getGroup () const
const QString & getInstance () const
const QString & getContextValue (int32_t index) const
 retrieves a context property value.
const QArmApplicationDefinition & 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 QArmTransaction 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 QArmApplicationDefinition 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 QArmApplication and QArmTransaction 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 QArmApplication, they are set in the factory method and are immutable afterwards. In QArmTransaction, they are set at any time and processed each time a QArmTransaction::start() executes.

    The reason for the difference is that QArmApplication objects are not reused. One object is created per application instance. If another instance starts, a new QArmApplication 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 QArmApplication 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 QArmTransaction object for each transaction instance would result in unacceptable and unnecessary overhead. Instead, an QArmTransaction object is created and then reused over and over. Each executing transaction is represented by the paired QArmTransaction::start()/QArmTransaction::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 QArmApplication object, it may not use any reference to the QArmApplication object, nor may it call any method of any object created using a reference to the QArmApplication object (e.g., creating an instance of QArmTransaction). Any transactions that are currently in-process [QArmTransaction::start() executed but QArmTransaction::stop() not executed] will be discarded by implicitly executing the QArmTransaction::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::QArmApplication::QArmApplication ( const QArmApplicationDefinition &  definition,
const QString &  group = NullString,
const QString &  instance = NullString,
const QVector< QString > &  contextValues = NullVector 
)

Constructs the QArmApplication 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::QArmApplication::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 QArmInterface).
const QString& arm4::QArmApplication::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 QArmApplicationDefinition& arm4::QArmApplication::getDefinition (  )  const
Returns:
the metadata describing this application.
const QString& arm4::QArmApplication::getGroup (  )  const
Returns:
the group name this application is associated with, or a NullString.
Note:
See comments in the interface description above.
const QString& arm4::QArmApplication::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:18. © 2018 by MyARM GmbH