E2 — Adoptions, Take 2

Due Friday, 29 March 2024, 11:59:59pm.

Purpose The purpose of this milestone is to implement (most of) the shelter side of the STBU center in Elixir.

Programming Task

This milestone calls for implementing three major pieces of the animal shelter functionality:

1. Providing clients the means to view and adopt pets;

2. Enforcing play timeouts; and

3. Taking in new animals.

2.1 Initialization and Connecting Clients

Implement the module STBU.Interface.Entry with (at least) the following public functions:

• initialize_shelter/2. The function takes two arguments. The first is an io_device from which a JSON Configuration may be read. The second is a natural number specifying the number of milliseconds a client may play with a pet before incurring a timeout (c.f. Dawdling Clients).

  You have the option to register a name for your shelter process, in which case initialize_shelter/2 may return that name (atom).

  The function should return a PID corresponding to a process that returns the animal center. Clients will use the PID as the starting point of their interactions (see below).

A client may use the returned "shelter" PID to either initiate the adoption protocol or bring additional animals to the shelter. For this purpose, implement the module STBU.Interface.Shelter with (at least) the following public functions:

• view_pets/1. The function takes one argument, the address of the "shelter." It returns the PID of a "pet viewer" process that the client may then interact with according to the adoption protocol below. The identity (PID) of the "client" is the process calling the function.

• import_animals/2. The function’s first argument is the address of the "shelter" process. The second is an io_device from which a JSON array of Animals may be read. The function need not return any particular value, but it should not return until the shelter acknowledges the successful accomodation of the new animals.

  Reading from the provided io_device should not be performed in the client’s process. That is, if reading and decoding the information causes an error, that error should occur in the shelter process (or a helper), not the client’s.

Note. The intention of these module interfaces is to abstract the particular details of message formats and protocols away from clients. That is, you must design the particular data representation of messages, sequence of message sends and receives, and number of collaborating processes to implement the required behavior.

2.2 Adoption Protocol

The logical structure of the adoption protocol mirrors that of milestone 3 (Adoption Protocol), with some minor alterations to the data to accomodate the new setting. The client-facing interface will be provided by the module STBU.Interface.PetViewer, in which you will implement (at least) the following public functions:

• view_next/1. The sole argument is the PID of the client’s pet viewer process, as is the case for each of the three functions below. The function returns an Optional<PetView>, depending on whether another pet is available to view.

• try_play/1. The function should return :ok if the client succesfully plays with the pet and :error otherwise.

• try_adopt/1. The function should return :ok if the client succesfully adopts the pet and :error otherwise.

• finished/1. The function need not return a meaningful value, but it should lead to the termination of the pet viewer process.

Timeouts. In the event of a play timeout, the pet should return to its pen and the client should receive a PlayTimeout message:

2.3 Testing Task

Implement the module STBU.Test.EagerClient with (at least) the following public functions:

• start/2. This function should start a new process performing the behavior for an eager client (see Testing Task). The first argument is the address of the "shelter" process. The function’s second argument is the patience of the client. When the client process finishes, it should send an EagerClientResult message to the process that called the start/2 function.

2.4 Delivery

Your project should include the designated modules under the lib directory (see —Elixir, Mix) with the behavior described above, and succesfully build (i.e. with mix compile).