anchor.diff:  }
   --
   
  -Unless specified using other annotations, all public methods of implementations of this object will be assumed to modify the state of the object.
  -Please refer to the Narayana guide for details of how to exert finer grained control over the transactional behaviour of objects that implement
  -interfaces marked with the `@Transactional` annotation.
  +Classes which implement this interface are able to use additional annotations from Narayana to tell the STM
  +subsystem about things such as whether a method will modify the state of the object, or what state variables
  +within the class should be managed transactionally, e.g., some instance variables may not need to be rolled back
  +if a transaction aborts. As mentioned earlier, if those annotations are not present then defaults are chosen to
  +guarantee safety, such as assuming all methods will modify state.
  +
  +[source,java]
  +--
  +public class FlightServiceImpl implements FlightService {
  +    @ReadLock
  +    public int getNumberOfBookings() { ... }
  +    public void makeBooking(String details) {...}
  +    
  +    @NotState
  +    private int timesCalled;
  +}
  +--
  +
  +For example, by using the `@ReadLock` annotation on the `getNumberOfBookings` method, we are able to tell the
  +STM subsystem that no state modifications will occur in this object when it is used in the transactional
  +memory. Also, the `@NotState` annotation tells the system to ignore `timesCalled` when transactions commit or
  +abort, so this value only changes due to application code.
  +
  +Please refer to the Narayana guide for details of how to exert finer grained control over the transactional
  +behaviour of objects that implement interfaces marked with the `@Transactional` annotation.
   
   == Creating STM objects
   
  -The STM library needs to be told which objects it should be managing by providing a container for the transactional memory.
  -The default container (`org.jboss.stm.Container`) provides support for volatile objects that cannot be shared between JVMs
  -(although other constructors do allow for other models):
  +The STM subsystem needs to be told about which objects it should be managing. The Quarkus (aka Narayana) STM implementation
  +does this by providing containers of transactional memory within which these object instances reside. Until an object
  +is placed within one of these STM containers it cannot be managed within transactions and any state changes will
  +not possess the A, C, I (or even D) properties.
  +
  +Note, the term "container" was defined within the STM implementation years before Linux containers came along. It may
  +be confusing to use especially in a Kubernetes native environment such as Quarkus, but hopefully
  +the reader can do the mental mapping.
  +
  +The default STM container (`org.jboss.stm.Container`) provides support for volatile objects that can only be shared between
  +threads in the same microservice/JVM instance. When a STM-aware object is placed into the container it returns a handle
  +through which that object should then be used in the future. It is important to use this handle as continuing to access
  +the object through the original reference will not allow the STM subsystem to track access and manage state and
  +concurrency control.
   
   [source,java]
   --
  
positive.code:     provides a number of features for managing conflicting behaviour and these are covered in the Narayana STM manual).
  <6> Programmatically decide to abort the transaction which means that the changes made by the flight and taxi services are discarded.
  
  == Concurrency behaviour
  
  The goal of STM is to simplify object reads and writes from multiple threads.
  Threads are responsible for starting their own transactions before accessing
  a transactional object. The STM library will safely manage any conflicts between
  these threads. For example, if the access mode is pessimistic (the default),
  and a thread enters a transactional method then other threads may be blocked
  until the first thread leaves the method. This blocking behaviour may be modified
  using suitable STM annotations. Optimistic concurrency is also supported: in
  this mode conflicts are checked only at commit time and a thread may be forced
  to abort if another thread has made conflicting updates.
  
  Remark: sharing a transaction between multiple threads is possible but is currently
  an advanced use case only and the Narayana documentation should be consulted
  if this behaviour is required. In particular, STM does not yet support the features
  described in the link:context-propagation[Context Propagation guide].
  
negative.code: 
  <1> You need to tell each Container about the type of objects for which it will be responsible. In this example
      it will be instances that implement the FlightService interface.
  <2> Then you create an instance that implements `FlightService`. You should not use it directly at this stage because
      access to it is not being managed by the STM subsystem.
  <3> To obtain a managed instance, pass the original object to the STM `container` which then returns a reference
      through which you will be able perform transactional operations. This reference can be used safely from multiple threads.
  
  == Defining transaction boundaries
  
  Once an object is placed within an STM container the application developer can manage the scope of transactions
  within which it is used. There are some annotations which can be applied to the STM-aware class to have the
  container automatically create a transaction whenever a specific method is invoked.
  
  === Declarative approach
  
  If the `@NestedTopLevel` or `@Nested` annotation is placed on a method signature then the STM container will
  start a new transaction when that method is invoked and attempt to commit it when the method returns. If there is
  a transaction already associated with the calling thread then each of these annotations behaves slightly differently:
  the former annotation will always create a new top-level transaction within which the method will execute, so the enclosing
  transaction does not behave as a parent, i.e., the nested top-level transaction will commit or abort independently; the
  latter annotation will create a transaction with is properly nested within the calling transaction, i.e., that
  transaction acts as the parent of this newly created transaction.
  
  === Programmatic approach
  
  The application can programmatically start a transaction before accessing the methods of STM objects:
  
  [source,java]
  --
  