With the release of IVAAP 2.2 coming up, there are lots of new features to explore. Since more data sources have being added, the Software Development Kit (SDK) of IVAAP’s backend has also grown. As developers get acquainted with IVAAP’s Application Programming Interface (API), one often-asked question concerns the presence of a scopeUUID parameter in several method declarations: What is this scope, and why is it useful?
The purpose of IVAAP’s backend is to access the data from many data sources and present this data in a unified manner to the IVAAP HTML5 client. This backend is written in Java and accesses SQL databases, web services, basically any type of data store. Performance is key, and some data stores are faster to access than others. For example, web services tend to have much higher latency than SQL databases. In a web service configuration, a smart caching strategy is required so that the same web/HTTP calls are not made to the same data store twice while a service request is being fulfilled, regardless of its complexity. This is where the concept of scope comes in.
A scope is defined as a short-lived execution, and within this short lifetime, it’s generally OK to assume that two identical calls to the same data store will return the same result. The scopeUUID is a unique identifier of a scope. A scope is created automatically when an HTTP request is sent to a backend service, and disposed of when that entire request has been fulfilled. Depending of the performance characteristics of a data source, developers working on a data connector have the option to reuse cached information across the time span of a scope.
Scopes are needed because of the asynchronous nature of IVAAP’s execution architecture. Asynchronous code is not as common as synchronous code; it’s more complex to write, but tends to withstand higher workloads, which is a key requirement for IVAAP. If service executions were performed synchronously, the scope would be strongly associated with the current thread, and developers would typically cache the same information in a ThreadLocal variable instead.
Identifying the Source of a Method Call
While the most common use of scopes is for caching, being able to identify the source of a method call can be quite useful when running your application. In a synchronous world, the Java call stack provides this information. But in an asynchronous world where messages are being passed between actors, this call stack provides very little useful information. The IVAAP API allows you to build a useful call stack while developing. For example, if your backend code makes a call to an external web service, but you’re not sure why, you can plug your own AbstractScopesController class to control when this scope is created, then plug your own AbstractActorsController class to track how actors spawn other actors within that scope.
A third typical usage of scopes is to help with the management of transactions. When you retrieve a connection from a SQL connection pool, knowing the scope allows you to decide whether to reuse the same connection instead of the first one from the pool. Transactions are tightly associated with connections, and, without a scope, you’d need to pass connections around while a transaction is in play. Passing a scopeUUID instead avoids this code clutter, allowing you to easily implement APIs that are truly data-source agnostic.
Scope: Just More Code Clutter?
This brings me to the main objection to scopes: “Isn’t passing a scopeUUID a code clutter of its own?” The answer lies in how a developer plans to use the IVAAP backend SDK. If you use this API to write synchronous code, the scopeUUID will appear to get in the way. If you use the same API to write asynchronous code, you’ll find that the internal maintenance of scopes doesn’t affect the implementation of your actors. The scopeUUID of a service request is passed automatically from one actor to the next, without the developer’s intervention. If your data source is fast enough that it doesn’t require caching, if you do not make use of transactions, your asynchronous code will not need to be aware of scopes. It’s only when you will have to troubleshoot the relationships between actors at runtime that you might come to appreciate its usefulness.