edu.unm.cs.cs351.tdrl.f06.p2
Interface World

public interface World

Objects of type World represent the "outside world" from which all customers and profit flow.

The simulator interacts with the World via two object types:

• Customer Information Token (CIT). The World generates tokens of this type to describe orders to the simulator/plant. Those tokens may represent:
  • New orders: The CIT.getPrevTransactionReceipt() field is null.
  • Change orders: The CIT.getPrevTransactionReceipt() is non-null and the CIT.isCancellation() is false.
  • Cancellation orders: The CIT.getPrevTransactionReceipt() is non-null and the CIT.isCancellation() is true.
• Order Receipts (OrderReceipt). The Simulator generates receipts of this type to indicate:
  • That an order has been recieved and is in the queue to be processed and filled.
  • When fulfilling an order via the deliver(int, OrderReceipt, ComputerOrder, boolean) method, to identify which order is being completed and should be cleared.

The basic order of operations for using an object of type World is:

1. Initialization
   1. Create a new instance of a World object (probably with an associated XRandom pseudo-random number generator)
   2. Call acknowledgeOrder(OrderReceipt,int) with a null receipt in order to get the arrival time of the first order.
2. Call getOrderAtTime(int) to receive a new CIT
3. Call acknowledgeOrder(OrderReceipt,int) to acknowledge that the order has been received and is being processed and to assign a unique order receipt to the order.
4. Call deliver(int, OrderReceipt, ComputerOrder, boolean) to fulfill an outstanding order.
5. (At the end of the simulation) Call finalReport(DiscrEventSimulator) to finalize the simulation and get a summary of results.

The World maintains a set of outstanding orders. These are orders that have been placed, but not yet filled. When the plant fills an order (by calling deliver(int, OrderReceipt, ComputerOrder, boolean)) the corresponding outstanding order is "cleared" -- that is, removed from the outstanding order set.

Version:

1.0

Author:

terran

Method Summary

int	acknowledgeOrder(OrderReceipt r, int time) This method is called by the simulator/factory when an order has been received (via the getOrderAtTime(int) method).
void	deliver(int time, OrderReceipt r, ComputerOrder delivered, boolean isFaulty) Called to indicate that an order has been completed and is being delivered to the customer.
String	finalReport(DiscrEventSimulator finalState) Generate a report and assessment of the final performance of the Grell plant at the end of the simulation.
CIT	getOrderAtTime(int time)

Method Detail

deliver

void deliver(int time,
             OrderReceipt r,
             ComputerOrder delivered,
             boolean isFaulty)

Called to indicate that an order has been completed and is being delivered to the customer. Calling this will resolve a single outstanding order and remove it from the set of outstanding orders. The World will use the delivery information to adjust the customer satisfaction information.

The following conditions are illegal and will cause an IllegalArgumentException to be thrown:

• If the simulator attempts to fulfill an order that was never actually placed, or if the simulator attempts to fulfill an order that was previously cancelled.
• If the simulator attempts to deliver an order at a time step before or equal to the time step at which the order was placed.
• If the simulator delivers an ComputerOrder that wasn't what the customer asked for.

Note that it is required that the delivered computer type actually match the ordered type. (That is, the type of the most recent order, if there has been a change order placed.) In this discrete event simulation, we encompass all possible manufacture errors in the single boolean flag isFaulty.

Parameters:

time - Time stamp at which the order is delivered.

r - Original order receipt that was generated for this order.

delivered - Type of computer that was actually delivered (should be the same as the type in the most recent order!)

isFaulty - true iff the delivered computer was broken in some way, because some assembler somewhere screwed up.

Throws:

IllegalArgumentException - If any of the illegal conditions described above occurs.

getOrderAtTime

CIT getOrderAtTime(int time)

Parameters:

time - Time for which an arrived order is being requested

Returns:

Customer information token for the order that arrived at time time.

Throws:

IllegalArgumentException - if time doesn't match arrival time of the next customer token.

acknowledgeOrder

int acknowledgeOrder(OrderReceipt r,
                     int time)

This method is called by the simulator/factory when an order has been received (via the getOrderAtTime(int) method). This notifies the customer that the order has been received and is being processed. It also assigns an order number to a customer that they can later use to communicate back with the factory and request a change or cancellation. When this is called, it returns the time that the next order will be placed, which allows the event simulator to know when next to call getOrderAtTime(int).

Note that this method is called every time an order is placed, including cancellation and change orders. For new orders, the receipt is a new receipt and should include a newly-generated (unique) order ID. For change and cancellation orders, the receipt is the same receipt generated for the original order, including the same order ID.

To get the whole simulation ball rolling, this method can be called with a null receipt. It will then generate the timestamp of the first order event and return that. After the first such call, it is an error to pass null into this method, and it will throw a NullPointerException in response.

Parameters:

r - Receipt for the most recently placed order, including a (factory-generated) order ID. null on the first call, to initialize the world simulator.

time - Time stamp at which receipt is returned. Should be the same as the time stamp at which the order was retrieved via getOrderAtTime(int).

Returns:

Time stamp for the next upcoming order event.

Throws:

NullPointerException - if r==null any time after the first call.

finalReport

String finalReport(DiscrEventSimulator finalState)

Generate a report and assessment of the final performance of the Grell plant at the end of the simulation. This should be run when the simulation terminates to get a human-readable assessment of how well the company did, both financially and in terms of customer satisfaction.

Parameters:

finalState - Final state of the simulation

Returns:

Human-readable string representation