TariffSubscription (Power TAC server interface 1.6.0 API)

java.lang.Object
- org.powertac.common.TariffSubscription

```
@Domain
public class TariffSubscription
extends Object
```
A TariffSubscription is an entity representing an association between a Customer and a Tariff. Instances of this class are not intended to be serialized. You get one by calling the subscribe() method on Tariff. If there is no current subscription for that Customer (which in most cases is actually a population model), then a new TariffSubscription is created and returned from the Tariff.

Author:

John Collins, Carsten Block

Constructor Summary

Constructors
Constructor and Description
`TariffSubscription(org.powertac.common.CustomerInfo customer, long tariffId)` Alternate constructor for logtool analyzers in which Tariffs cannot be reconstructed.
`TariffSubscription(org.powertac.common.CustomerInfo customer, org.powertac.common.Tariff tariff)` You need a CustomerInfo and a Tariff to create one of these.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`deferredUnsubscribe(int customerCount)` Handles the actual unsubscribe operation.
`void`	`ensureRegulationCapacity()` Ensures that regulationAccumulator is non-null - needed for non-regulatable customer models
`double`	`getCurtailment()` Returns the regulation in kwh, aggregated across the subscribed population, for the previous timeslot.
`org.powertac.common.CustomerInfo`	`getCustomer()`
`int`	`getCustomersCommitted()`
`int`	`getExpiredCustomerCount()` Returns the number of individual customers who may withdraw from this subscription without penalty.
`long`	`getId()`
`double`	`getRegulation()` Returns the regulation quantity exercised per member in the previous timeslot.
`RegulationAccumulator`	`getRemainingRegulationCapacity()` Returns the maximum aggregate up-regulation possible after the customer model has run and possibly applied economic controls.
`org.powertac.common.Tariff`	`getTariff()`
`long`	`getTariffId()`
`double`	`getTotalUsage()`
`org.powertac.common.Tariff`	`handleRevokedTariff()` Handles the subscription switch in case the underlying Tariff has been revoked.
`boolean`	`hasRegulationRate()` True just in case this subscription allows regulation.
`void`	`postBalancingControl(double kwh)` Posts a BalancingControlEvent to the subscription and generates the correct TariffTransaction.
`void`	`postRatioControl(double ratio)` Posts the ratio for an EconomicControlEvent to the subscription for the current timeslot.
`void`	`setCustomersCommitted(int value)`
`void`	`setRegulation(double newValue)`
`void`	`setRegulationCapacity(RegulationCapacity capacity)` Communicates the ability of the customer model to handle regulation requests.
`void`	`subscribe(int customerCount)` Subscribes some number of discrete customers.
`void`	`unsubscribe(int customerCount)` Removes customerCount customers (at most) from this subscription, posts early-withdrawal fees if appropriate.
`void`	`usePower(double kwh)` Generates and posts a TariffTransaction instance for the current timeslot that represents the amount of production (negative amount) or consumption (positive amount), along with the credit/debit that results.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - TariffSubscription
```
public TariffSubscription(org.powertac.common.CustomerInfo customer,
                          org.powertac.common.Tariff tariff)
```
    You need a CustomerInfo and a Tariff to create one of these.
  - TariffSubscription
```
public TariffSubscription(org.powertac.common.CustomerInfo customer,
                          long tariffId)
```
    Alternate constructor for logtool analyzers in which Tariffs cannot be reconstructed.
- Method Detail
  - getId
```
public long getId()
```
  - getCustomer
```
public org.powertac.common.CustomerInfo getCustomer()
```
  - getTariff
```
public org.powertac.common.Tariff getTariff()
```
  - getTariffId
```
public long getTariffId()
```
  - getCustomersCommitted
```
public int getCustomersCommitted()
```
  - setCustomersCommitted
```
@StateChange
public void setCustomersCommitted(int value)
```
  - getTotalUsage
```
public double getTotalUsage()
```
  - subscribe
```
@StateChange
public void subscribe(int customerCount)
```
    Subscribes some number of discrete customers. This is typically some portion of the population in a population model. We assume this is called from Tariff, as a result of calling tariff.subscribe(). Also, we record the expiration date of the tariff contract, just in case the tariff has a minDuration. For the purpose of computing expiration, all contracts are assumed to begin at 00:00 on the day of the subscription.
  - unsubscribe
```
public void unsubscribe(int customerCount)
```
    Removes customerCount customers (at most) from this subscription, posts early-withdrawal fees if appropriate.
  - deferredUnsubscribe
```
@StateChange
public void deferredUnsubscribe(int customerCount)
```
    Handles the actual unsubscribe operation. Intended to be called by the TariffMarket (phase 4) to avoid subscription changes between customer consumption/production and balancing.
  - handleRevokedTariff
```
public org.powertac.common.Tariff handleRevokedTariff()
```
    Handles the subscription switch in case the underlying Tariff has been revoked. The actual processing of tariff revocations, including switching subscriptions to superseding tariffs, is deferred to be handled by the tariff market.
  - usePower
```
public void usePower(double kwh)
```
    Generates and posts a TariffTransaction instance for the current timeslot that represents the amount of production (negative amount) or consumption (positive amount), along with the credit/debit that results. Also generates a separate TariffTransaction for the fixed periodic payment if it's non-zero. Note that the power usage value and the numbers in the TariffTransaction are aggregated across the subscribed population, not per-member values. This is where the signs on energy and cost are inverted to convert from the customer-centric view in the tariff to the broker-centric view in the transactions.
  - getCurtailment
```
public double getCurtailment()
```
    Returns the regulation in kwh, aggregated across the subscribed population, for the previous timeslot. Intended to be called by Customer models only. Value is non-negative for consumption power types, non-positive for production types. For storage types it may be positive or negative. NOTE: this method is not idempotent; if you call it twice in the same timeslot, the second time returns zero.
  - getRegulation
```
public double getRegulation()
```
    Returns the regulation quantity exercised per member in the previous timeslot. For non-storage devices, only up-regulation through curtailment is supported, and the result will be a non-negative value. For storage devices, it may be positive (up-regulation) or negative (down-regulation). Intended to be called by customer models. NOTE: This method is not idempotent, because the regulation quantity is reset to zero after it's accessed.
  - setRegulation
```
public void setRegulation(double newValue)
```
  - setRegulationCapacity
```
public void setRegulationCapacity(RegulationCapacity capacity)
```
    Communicates the ability of the customer model to handle regulation requests. Quantities are per-member. NOTE: This method must be called once/timeslot for any customer that offers regulation capacity, because otherwise the capacity will be carried over from the previous timeslot.
  - ensureRegulationCapacity
```
public void ensureRegulationCapacity()
```
    Ensures that regulationAccumulator is non-null - needed for non-regulatable customer models
  - hasRegulationRate
```
public boolean hasRegulationRate()
```
    True just in case this subscription allows regulation.
  - postRatioControl
```
@StateChange
public void postRatioControl(double ratio)
```
    Posts the ratio for an EconomicControlEvent to the subscription for the current timeslot.
  - postBalancingControl
```
@StateChange
public void postBalancingControl(double kwh)
```
    Posts a BalancingControlEvent to the subscription and generates the correct TariffTransaction. This updates the regulation for the current timeslot by the amount of the control. A positive value for kwh represents up-regulation, or an increase in production - in other words, a net gain for the broker's energy account balance. The kwh value is a population value, not a per-member value.
  - getRemainingRegulationCapacity
```
public RegulationAccumulator getRemainingRegulationCapacity()
```
    Returns the maximum aggregate up-regulation possible after the customer model has run and possibly applied economic controls. Since this is potentially accessed through the balancing market after customers have updated their subscriptions, it's possible that the value will have to be changed due to a change in customer count. TODO: may need to be modified -- see issue #733.
  - getExpiredCustomerCount
```
public int getExpiredCustomerCount()
```
    Returns the number of individual customers who may withdraw from this subscription without penalty. Should return the total customer count for a non-expiring tariff.

Class TariffSubscription

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TariffSubscription

TariffSubscription

Method Detail

getId

getCustomer

getTariff

getTariffId

getCustomersCommitted

setCustomersCommitted

getTotalUsage

subscribe

unsubscribe

deferredUnsubscribe

handleRevokedTariff

usePower

getCurtailment

getRegulation

setRegulation

setRegulationCapacity

ensureRegulationCapacity

hasRegulationRate

postRatioControl

postBalancingControl

getRemainingRegulationCapacity

getExpiredCustomerCount