Skip to main content
Skip table of contents

Retrieving Persistent State Metadata with the PersistentStateControl Adapter

The Persistent State Control Adapter gives access to persistent state metadata directly from within a service (self context). The same data can be retrieved using the xUML Runtime API.

If you want to retrieve metadata of persistent state of the very same service, always use the Persistent State Control Adapter.
If you want to retrieve data from other services, use the xUML Runtime API.

What a <<PersistentStateControl>> action does can be controlled via tagged value action. Currently the following actions are supported:

Example File (Builder project Advanced Modeling/PState):

<your example path>\Advanced Modeling\PState\uml\pstatePurchaseOrder.xml

Listing all Persistent State Owners

In Load Balancing context, when e.g. running multiple Bridges, you can setup persistent state services to share persistent state objects. The persistent state objects are distinguished by an owner and owner id reflecting the actual service that owns these objects.
Prerequisite is that these services share the same persistent state database, see Load Balanced Persistent State for more details.

listOwners lists all owners that are maintaining persistent state objects of the current service.
For more information on how to manage ownership of persistent state objects, refer to Persistent State Ownership.

Parameters

NameTypeDirectionMandatoryDescription
ownersArray of Owner out(tick)The adapter returns an array of owner details.

Getting the Name of an Owner

getOwnerName returns the name of the current owner (self).
For more information on how to manage ownership of persistent state objects, refer to Persistent State Ownership.

Parameters

NameTypeDirectionMandatoryDescription
ownerNameStringout(tick)The adapter returns the name of the current owner as a String.

Listing all Available Persistent State Classes

listClasses returns an array list of all available persistent state classes of the current service (self). By specifying includeObjectCount = true, you can get the actual object count per class.

Parameters

NameTypeDirectionMandatoryDescriptionAllowed Values
includeObjectCountBooleanin
Specify whether to include an object count per class to the response.trueInclude an object count per class.
falseDo not include an object count per class (default).
classesArray of ClassInfo out(tick)The adapter returns a list of classes as an Array of ClassInfo.

Getting Object Counters per Class

getClassCounters returns an array list of all available persistent state classes of the current service (self) and their actual counters. Refer to type ClassCounters for more details on which counters are available.

Parameters

NameTypeDirectionMandatoryDescription
countersArray of ClassCounters out(tick)The adapter returns the object counters per class as an Array. Refer to type ClassCounters for more details on the counters.

Getting the Persistent State Class Metadata

getClassMetadata returns the metadata of a given class. The action returns an array list of all attributes and their types.

Parameters

NameTypeDirectionMandatoryDescription

class

Stringin(tick)Specify the name of the class to get metadata of. You can provide the value dynamically or via tagged value class on the adapter action.
classMetadata ClassMetadata out(tick)

The adapter returns a ClassMetadata object, listing all attributes and their metadata, and the primary and search keys.

The array of primary keys is sorted in definition order.

Querying Persistent State Objects of a Given Class

With action queryObjects you can query the persistent state database for objects of a given class. Queries can use simple query conditions and complex query conditions (and/or).

Using queryObjects, the persistent state database can be search by the search keys that are defined on the persistent state class.

Queries are steered by parameter selectQuery that, on the one hand, specifies global search data like searching by object dates and search order, and, on the other hand, can hold complex search queries.

Parameters

NameTypeDirectionMandatoryDescriptionAllowed Values
selectQuerySelectObjectsQueryin(tick)Provide a search query..
includeObjectDataBooleanin
Specify whether to include object data of the matching objects to the response.trueReturn object data of the found objects.
falseOnly return the objects metadata (default).
objectEntriesArray of ObjectEntry out(tick)The adapter returns an array of objects and some basic object metadata per object.

Attribute condition of type SelectObjectsQuery holds the custom search query itself. Attribute orderBy holds sorting specifications.

Building a Simple Query

By using only one condition of type SimpleQueryCondition you can build a simple query. Find below a the activity diagram of a simple query that returns all purchase orders with 2 or more open items.

selectQuery.conditions holds the query condition. It consists of

  • name of the search key attribute to use for comparison
  • an operator for the comparison
  • a value to compare against

Valid operators are:

OperatorDescription
=Equal.
!=Not equal.
<Less than.
<=Less or equal.
>Greater than.
>=Greater or equal.
~Like (SQL).
!~Not like (SQL).
nullNull.
!nullNot null.

All operators will be translated to SQL operators, so the relational operators will not work as expected if any of the operands is NULL. The Runtime will throw error PSADSM/46 in this case.

Exception: The =  and != operators will map to IS NULL and IS NOT NULL in this case.

Querying does only work on persistent state attributes that have been marked as <<SearchKey>>. Also, if you apply this stereotype to a persistent state attribute later on, all previous persistent state objects are disregarded if searching with this key.


Building a Complex Query

Using type ComplexQueryCondition, you can build a complex query of multiple simple queries. They can be joined together by a disjunction (or) or a conjunction (and).

Assuming you have myCondition1 and myCondition2 of type SimpleQueryCondition, you can join them to an and query with an andQuery of type AndQueryCondition like:

CODE
create selectQuery;
create myCondition1;
create myCondition2;
create andQuery;

set selectQuery.sortByUpdate = "DESC";

set myCondition1.attribute = "openItems";
set myCondition1.operator = ">=";
set myCondition1.value = openItems;

set myCondition2.attribute = "customerID";
set myCondition2.operator = "=";
set myCondition2.value = "4711";

append myCondition1 to andQuery.condition;
append myCondition2 to andQuery.condition;

set selectQuery.condition = andQuery;

In this case, one of the to conditions could also be a complex condition instead of a simple one. Like that you can build very complex combinations of and and or queries.

Sorting the Query Results

You can sort the results that are returned by persistent state attributes and/or by persistent state meta data (creation timestamp and update timestamp).

SortingAttribute(s) of SelectObjectsQueryDescription
Only by persistent state meta data
  • sortByCreation
  • sortByUpdate

Provide a sorting direction with the sortByCreation and sortByUpdate attributes of SelectObjectsQuery (ASC, DESC).

By persistent state attributes
  • orderBy

Create an array of objects of type AttributeSortCondition and provide it with the orderBy attribute of SelectObjectsQuery.

sortByCreation and sortByUpdate will be completely ignored in this case.

By a mixture of persistent state attributes and meta data
  • orderBy

The array orderBy can hold objects of AttributeSortCondition and MetaAttributeSortCondition as they both derive from SortCondition (see class diagram above). Provide the meta attribute to sort by with an object of type MetaAttributeSortCondition.

sortByCreation and sortByUpdate will be completely ignored in this case.

Deleting Persistent State Objects

deleteObject deletes the object identified by class and objectId.

Deleting objects directly via deleteObject is not best practice and can lead to odd side effects. Best practice is to model this in the state machine.

Parameters

NameTypeDirectionMandatoryDescriptionExample
classStringin(tick)Specify the name of the class to delete objects from.PurchaseOrder 
objectIdStringin(tick)Specify the id of the object to delete.000100058a79cb967f6e00000079 

Parameter Types

Class 

AttributeTypeDescriptionAllowed Values
AndQueryConditionconditionType String

Type of the condition.

conjunction Marks the condition as conjunction (and) of simple queries (default and not changeable).
conditionArray of QueryCondition

List of simple queries that are related by and


AttributeSortConditon




nameString


Name of the persistent state attribute to sort by.

a valid persistent state attribute name with stereotype <<SearchKey>>
directionString

Sort direction as defined on SortCondition.

ASCAscending sorting (default).
DESC

Descending sorting.

ClassAttributeMetadata

nameStringName of the persistent state attribute.
typeString

Type of the persistent state attribute, e.g. 

  • String (for base types)
  • UML class id of the type, urn:Services.PurchaseOrderService.Classes.Item

ClassCountersnameStringName of the persistent state class.
countIntegerObject count.
stalledCountIntegerCount of objects that are stalled.
statesArray of StateCountersList of states including count of objects in this state.
ClassInfonameStringName of the persistent state class.
countIntegerObject count.
ClassMetadatanameStringName of the persistent state class.
attributesArray of ClassAttributeMetadataList of class attributes and their metadata.
primaryKeysArray of String

List of attributes that are marked as primary key with stereotype <<PrimaryKey>>.

The array of primary keys is sorted in definition order.


searchKeysArray of String

List of attributes that are marked as search key with stereotype <<SearchKey>>.


MetaAttributeSortCondition

nameString

Name of the persistent state meta attribute to sort by.creationSort by creation date.
updateSort by update date.
directionString

Sort direction as defined on SortCondition.

ASCAscending sorting (default).
DESC

Descending sorting.

ObjectEntryidStringUnique identifier of the persistent state object.
nameStringName of the persistent state object.
creationDateTimeCreation date of the object.
lastUpdateDateTimeDate object has been last updated.
statesArray of StringList of states the object is in.
objectAny

Copy of the persistent state object.

object contains the same content as would be returned by getObjectCopy of the Persistent State Adapter. 


OrQueryConditionconditionType String Type of the condition. disjunction Marks the condition as disjunction (or) of simple queries (default and not changeable).
conditionArray of QueryConditionList of simple queries that are related by or.
Owner

idStringOwner id.
For more information on how to manage ownership of persistent state objects, refer to Persistent State Ownership.

compositeNameStringComposite name from the xUML model.
hostStringName of the host that runs the owner.
lastStartupDateTime

Last recorded service startup.


lastShutdownDateTimeLast recorded service shutdown.
ownedObjectsIntegerCount of owned objects.
isSelfBooleanTrue, if the current service is the owner.trueThe current service is the owner.
false

The current service is not the owner.

QueryCondition


SimpleQueryConditionconditionType String

Type of the condition.

simple Marks the condition as simple query condition (default and not changeable).
attributeString

Name of the search key attribute to use for comparison.

valid name of an existent persistent state class attribute that has stereotype <<SearchKey>>
operatorString

Operator for the comparison of attribute and value.

All operators will be translated to SQL operators, so the relational operators will not work as expected if any of the operands is NULL. The Runtime will throw error PSADSM/46 in this case.

Exception: The =  and != operators will map to IS NULL and IS NOT NULL in this case.

=Equal.
!=Not equal.
<Less than.
<=Less or equal.
>Greater than.
>=Greater or equal.
~Like (SQL).
!~Not like (SQL).
nullNull.
!nullNot null.
valueAny

Value to compare the attribute against.

Only base types allowed. The value must match the type of the specified attribute

SelectObjectsQuery


classifierStringName of the persistent state class to query.
creationFromDateTimeCreation date from.
creationToDateTimeCreation date to.
sortByCreationString

Sort by creation date (ASC/DESC). Relates to sortByUpdate.

  • If sortByCreation and sortByUpdate are both NULL, the resulting order is unspecified.
  • If both, sortByCreation and sortByUpdate are set, the result is sorted update first, creation second.
  • If you provide an invalid value, the Runtime will throw an exception.

ASCSort by creation date in ascending order.
DESCSort by creation date in descending order.
updateFromDateTimeUpdate date from.
updateToDateTimeUpdate date to.
sortByUpdateString

Sort by update date (ASC/DESC). Relates to sortByCreation.

  • If sortByCreation and sortByUpdate are both NULL, the resulting order is unspecified.
  • If both, sortByCreation and sortByUpdate are set, the result is sorted update first, creation second.
  • If you provide an invalid value, the Runtime will throw an exception.

ASCSort by date of last update in ascending order.
DESCSort by date of last update in descending order.
limitIntegerLimit the count of returned objects. Default is 1000.Default is 1000 objects.
stateArray of String

List of states.

A persistent state object must be in one of the states to be part of the result set (disjunction).


conditionQueryConditionQuery condition as described further above (see Querying Persistent State Objects of a Given Class).
skipInteger

Skip the number of objects provided with skip. Together with limit, this allows to implement pagination.

When using this feature with Oracle or SQL Server databases, you need at least the following database versions:

  • Oracle 12c
  • SQL Server 2012

orderByArray of SortCondition

Provide sort conditions (list of persistent state attributes and direction). This array is translated into an ORDER BY clause and added to the related query statement.

If orderBy is used, specified sortByCreation and sortByUpdate are completely disregarded. Instead use the provided meta attributes creation and update.


SortCondition

directionString

Sort direction.ASCAscending sorting (default).
DESC

Descending sorting.

StateCounters

nameStringName of the state.
countIntegerCount of objects in this state.
stalledCountIntegerCount of stalled objects in this state.
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.