}
/**
- * Terminology:
- *
- * - Credits
- * The analog of money. Credits are the `universal money` within Aquarium.
- *
- * - Resource
- * A billable/chargeable entity. We generally need credits to use a resource. When a resource is used,
- * then consume credits. Examples of resources are the `download bandwidth` and, respectively,
- * the 'upload bandwidth', the `disk space` and the `VM time` to name a few.
- *
- * - User
- * An owner of resources and credits.
- *
- * - Resource event
- * An event that is generated by a system, which is responsible for the resource and describes a
- * state change for the resource. In particular, a resource event records the time when that state
- * change occurred (`occurredMillis` attribute) and the changed value (`value` attribute).
- *
- * - Resource event store
- * A datatabase, in the general sense, where resource events are stored.
- *
- * - Cost policy
- * A cost policy refers to a resource and it is the policy used in order to charge credits for
- * resource usage.
- *
- * - "On/Off" cost policy
- * A particular cost policy for resource events that come in "on"/"off" pairs.
- * In this case the respective resource can only be (from the accounting/billing perspective) in two
- * states, namely "on" and "off". The respective resource events record the resource changes between
- * these two states. It is not the responsibility of Aquarium to guarantee correct interleaving of
- * "on"/"off" resource events.
- *
- * - "On/Off" resource event
- * A resource event for which the associated resource has an "On/Off" cost policy.
- *
- * - "On" resource event
- * An "on/off" event which actually records the "on" state for the particular resource it refers to.
- *
- * - "Off" resource event
- * An "on/off" event which actually records the "off" state for the particular resource it refers to.
- *
- * - Wallet entry
- * The entity that describes an accounting event and its corresponding credit value.
- * For example, downloading files uses the download bandwidth and this costs credits. The exact
- * cost, which is determined using the corresponding cost policy of the event, is recorded
- * in one or more wallet entries.
- *
- * - Finalized wallet entry
- * It is a wallet entry whose recorded credits (its credit value) can be taken into account for
- * billing the respective user (the resource owner).
- * When we say that a wallet entry is in a finalized state, we mean that it is a finalized wallet entry, as
- * described above.
- *
- * - Pending or Non-finalized wallet entry
- * It is a wallet entry whose recorded credits (probably having a zero value) cannot be taken into
- * account for billing the respective resource owner. Pending wallet entries are introduced to handle
- * the "on/off" resource events.
- * When we say that a wallet entry is in/having a pending state, we mean that it is in a pending or
- * non-finalized wallet entry, as described above.
- *
- * - Wallet store
- * A database, in the general sense, where wallet entries are stored.
- *
- * - User Bill
- * A, usually, periodic statement of how many credits the user has consumed.
- * It may contain detailed analysis that relates consumed credits to resources.
- *
- * - Billable or Chargeable wallet entry
- * A wallet entry that can participate in the creation of the user Bill.
- * A wallet entry is billable if and only if it is finalized.
- *
- * - Processed resource event
- * A resource event which has generated wallet entries.
- * We may also designate a processed resource event as `partially processed` in order to distinguish it
- * from a `fully processed` resource event.
- *
- * - Fully processed resource event
- * A resource event which has no pending wallet entries or has no pending wallet entries with corresponding new
- * and finalized wallet entries (the meaning of the `corresponding` wallet entries will become
- * obvious in action A2 below).
- *
- *
- * When an event is processed, there are three possible actions as an outcome, namely A1, A2, A3:
- *
- * - A1. Wallet entries are created. This happens *always*. Each resource event may create more than one
- * wallet entries. The credit value associated with each wallet entry may be zero credits but we
- * always generate wallet entries even those with zero credit values.
- *
- * We say that the event that causes the generation of wallet entries is the `generator` event.
- *
- * The semantics of wallet entry creation depend on whether the original event is an "on/off" event
- * or not.
- *
- * - If the event is an "on/off" event, then
- * - If it is an "on" event, then one and only one new wallet entry is created having a pending state.
- * The credit value of this wallet entry is zero and its `occurredMillis` attribute is the same
- * as the `occurredMillis` attribute of the generator event.
- *
- * So what we actually do in this case is to record the "on" state with a non-billable wallet entry.
- * ==> TODO: How is tis related to the (later) expecting "off" state and corresponding (to the "off"
- * TODO: state) wallet entries?
- *
- * - If it is an "off" event, then we need to find the corresponding "on" event.
- * As long as we have the corresponding "on" event, then based on the relative timespan between
- * the two "on/off" events and the corresponding resource policy we compute a series of *new*
- * and *finalized* wallet entries. Each new wallet entry has an `occurredMillis` attribute equal to the
- * `occurredMillis` attribute of the original, pending, wallet entry. We then say that the new
- * wallet entries _correspond_ to the original, pending wallet entry.
- * ==> TODO: verify that the semantics of `occurredMillis` for the new wallet entries, as defined
- * TODO: above, are correct.
- *
- * ==> TODO: What do we do with the old, pending wallet entry? Do we keep it or do we delete it?
- *
- * The new wallet entries are generated according to Algorithm W2.
- *
- * - If the event is not an "on/off" event then, by design, it can directly generate one or more
- * finalized wallet entries. These wallet entries are generated by Algorithm W1.
- *
- * - A2. As a byproduct of the above, the user credits total is updated.
- *
- * For this, we just use the chargeable wallet entries created from action A1. Non-chargeable wallet
- * entries are ignored completely.
- *
- * - A3. Relevant resource state (some value) is updated. For example, the total bandwidth up value is
- * increased by the amount.
- *
- * Since a resource event records the changed value for the resource, we can easily update the current
- * value for the resource.
- *
- * Under ideal circumstances, whenever a resource event arrives, we immediately process it and, so, the steps
- * described in the above actions are what it only takes to get to the new state.
- *
- * But it may so happen that the above event processing procedure may be interrupted. For example, an Aquarium
- * component or external dependency may fail. In such cases, when a resource event arrives we cannot safely assume
- * that it is the most recent unprocessed event. It is then that we have to take action. And since, in general
- * and from the perspective of a newly arriving resource event we are not certain if a failure has happened the
- * following assumption is valid:
- *
- * - For each arriving resource event, it is possible that there exist events that arrived previously but which
- * have not been partially or fully processed.
- *
- * So, on arrival of a new event, we need to search our event and wallet stores to find those unprocessed events
- * and process them in succession, as if they are newly arrived.
- *
- * In effect and in the most general case, we never process one event at a time but more than one resource
- * events. Their processing order is the ascending order of their `occurredMillis` attribute.
- * ==> TODO: Verify that this semantics of the processing order is correct.
- *
- *
- * We will need the following algorithms:
- *
- * Algorithm W1: Given an non "On/Off" resource event, generate its wallet entries.
- *
- * Algorithm W2: Given an "Off" resource event and the corresponding "On" resource event, generate
- * the corresponding wallet entries.
- *
- * Algorithm OnOff: Given an "Off" resource event, find its corresponding "On" resource event.
- *
- * Algorithm F: Given a newly arrived resource event, find the exact list of all unprocessed events up to the new
- * one.
- * Algorithm P: Process a resource event as if it is the most recent unprocessed one.
- *
- * The implementations are as follows:
- *
- * ============
- * Algorithm W1
- * ============
- * - Input
- * - A non-"on/off" resource event
- *
- * - Output
- * - The respective wallet entries
- *
- * - Implementation
- * TODO: This is done in Accounting.chargeEvents
- *
- * ============
- * Algorithm W2
- * ============
- * - Input
- * - An "off" resource event
- * - The corresponding "on" resource event
- *
- * - Output
- * - The respective wallet entries
- *
- * - Implementation
- * TODO: Trivial
- *
- * ===============
- * Algorithm OnOff
- * ===============
- * - Input
- *
- * ===========
- * Algorithm F
- * ===========
- * Input: A resource event (e).
- * Output: A list (l) of all unprocessed resource events up to (e).
- *
- *
- *
- */
- private[this] def thisIsJustForTheDoc: Unit = {
-
- }
-
- /**
* Find and process older resource events.
*
* Older resource events are found based on the latest credit calculation, that is the latest
projects / aquarium / commitdiff