Tariff publication story - Pyosch/powertac-server GitHub Wiki

up
A broker may add a new Tariff or modify an existing one at any time. This story deals with the TariffMarket and associated server components that deal with the incoming message traffic about tariffs.

TariffSpecification and its associated Rates and HourlyCharges represent new tariffs. When they arrive from brokers, the broker proxy calls tariffMarketService.processTariff(spec), where each one is validated, wrapped with a Tariff, and stored in the database. A TariffTransaction is created by Accounting to represent the publication fee, and stored in the database. It can be retrieved from there (by Accounting, presumably) by querying its postedTime field, which is the simulation time at which it was created. Finally, TariffMarket returns a TariffStatus message which the broker-proxy returns to the originating broker.

Periodically (nominally 4 times/day), new tariffs are published to any entities (presumably Customer models) that implement the NewTariffListener interface and have registered with the TariffMarket. These entities may, of course, keep their own lists of tariffs, indexed by their own evaluation criteria, or they may request the current list of active tariffs from the TariffMarket. Finally, after new tariffs have been successfully published, the original TariffSpecification objects are broadcast to all brokers.

Here is a sequence diagram that outlines the tariff-publication scenario:

Brokers may send other messages related to Tariffs, which are also handled by the TariffMarket:

• TariffExpire represents a change in the expiration of an existing tariff. If the message is valid, and refers to a valid Tariff, then the expiration date of that Tariff is updated. If the Instant given in the TariffExpire message is null, then the expiration instant is set to the current simulation time.
• TariffRevoke represents the immediate revocation of a tariff. If the message is valid and refers to a valid Tariff, then that Tariff is revoked immediately. This is done by marking the Tariff as KILLED. Periodically, the Customer must call the getRevokedSubscriptions() method on the TariffMarket, and then call handleRevokedTariff on each returned subscription. This work is delegated to the Customer in order to allow the Customer to know which Tariffs were revoked and respond accordingly. A fee is charged for revoking a tariff that has active subscriptions, by posting a TariffTransaction to the database.
• VariableRateUpdate represents setting a price on a future timeslot for a variable Rate on some Tariff. The message is validated, and the rate set.

The tariff-market provides methods for the Customer to interact with tariffs.

• getActiveTariffList(powerType) returns the unexpired tariffs available for the given PowerType. Customers use this method to find tariffs to evaluate.
• getRevokedSubscriptionList(customerInfo) returns the customer's TariffSubscriptions that are connected to revoked Tariffs and which have non-zero customer counts. Each Customer must call this method at least once/day, and then call handleRevokedTariff() on each of the returned tariff subscriptions. The result will be a new subscription (assuming the tariff was actually revoked) to the superseding tariff, or to the default tariff if no superseding tariff has been set by the broker.
• getDefaultTariff(powerType) returns the default tariff for the given PowerType. This is used by the handleRevokedTariff method on TariffSubscription, and may also be used by Customers to compare the terms of the default Tariff with other tariffs.
• setDefaultTariff(tariff) is used by the default Broker to publish the initial default tariffs. There is no reason for a customer to call this.