Understanding ThingWorx Transactions
Stating with ThingWorx 9.3.2., the following changes have been introduced for service authoring.
Categories of Database Operations
In ThingWorx Platform, database operations are classified into three categories:
• Data write operations, such as property writes that are always batched.
• Data read operations that were updated in ThingWorx 9.3.2 to eagerly release their transactions.
• Model operations that acquire a transaction and then hold it until the top-level service finishes.
Model operations are referred to instead of database operations because not all actions dealing with database are performed synchronously and, therefore immediately use a connection.
Model operations are those that affect the system entities. For example:
• Property definition changes: adding, removing, changing the basetype, and so on.
• Configuration changes.
Data operations are database operations performed asynchronously, and they are potentially batched for efficiency. For example:
• Updating a property value, even if persistent.
• Adding an entry to a DataTable, Stream, or ValueStream.
Platform Services that Use Eager Transactions
This section lists ThingWorx Platform services that eagerly release their transaction.
• DataTableThing
◦ GetDataTableEntries
◦ GetDataTableEntryByKey
◦ GetDataTableEntryCount
◦ FindDataTableEntries
◦ QueryDataTableEntries
◦ SearchDataTableEntries
• Things that use the "Stream" ThingTemplate
◦ GetStreamEntryCount
◦ QueryStreamData
◦ QueryStreamEntries
◦ QueryStreamEntriesWithData
◦ GetStreamEntry
• Things that use the ValueStream or RemoteValueStream ThingTemplates
◦ Get<Type>StreamEntry
▪ Integer, Long, Number, Boolean, Location, String, Vec2, Vec3, Vec4, ThingCode, InfoTable, Image, DateTime
◦ Query<Type>StreamEntries
▪ Integer, Long, Number, Boolean, Location, String, Vec2, Vec3, Vec4, ThingCode, InfoTable, Image, DateTime
◦ QueryMultiPropertyStreamEntries
By extension, Things that log their properties to a ValueStream can query the streams using these APIs.
Service Authoring Best Practices
This section recommends the best practices for the database connections to remain available in certain circumstances, but only if the services follow some general guidelines. These best practices include:
• Performing query operations before model changes
• Minimizing a long-running work done after model changes
Performing Long-Running Work When No Connection is in Use
Once a connection is retrieved for performing model operations, it cannot be released until the service terminates. Performing query operations before model operations allows a connection to be retrieved for querying and later be released while other work is being completed. If there is a long-running work that impacts the model, try to perform that work first before the connection is in use.
varthing = Things["SomeThing"];
// Instead of
thing.AddPropertyDefinition();// connection acquired
varhistory = thing.QueryPropertyHistory();
vardata = makeSomeExternalCalls(history);// connection held here
varvalue = calculateValue(data);// and here
thing.SetPropertyValue(value);
// Do this
varhistory = thing.QueryPropertyHistory();// connection acquired & released
vardata = makeSomeExternalCalls(history);// no connection
varvalue = calculateValue(data);// nor here
thing.AddPropertyDefinition();// connection acquired
thing.SetPropertyValue(value);
Using Asynchronous Services
If it is impossible to perform a long-running task after the model has been changed, you can use asynchronous services to ease the connection competition because it does not wait for a response before moving to the next command. Although it does not use fewer processing resources, it enables the service to be more responsive. Note that asynchronous services may not be viable in some cases, as they cannot return a value directly, but they can be helpful for the efficient resource usage.
varthing = Things["SomeThing"];
thing.AddPropertyDefinition();// connection acquired
asyncDoHttpRequestAndUpdateProperty(property);// request handled in another thread
// connection released (before async call completes)
What are Model Operations?
The documentation refers to model operations instead of database operations because not all actions that deal with the database are performed synchronously and, therefore immediately use a connection.
Model operations affect the system entities, as opposed to their data. Examples include:
• Property definition changes: adding, removing, changing base-type, and so on
• Configuration changes
Some database operations are performed asynchronously and are potentially arranged in groups for efficiency. These typically include data operations:
• Updating a property value, even if persistent.
• Adding an entry to a DataTable, Stream, or ValueStream.