CSCI E-168

Extension: Now due before 11:59 PM EST, Wed., Oct. 28

---

Errata

1. If you try to save a game with the same name as an existing game, delete the saved game, and all of its associated Pylons and Players. You do not need to provide a warning or ask the user if this is ok.
2. I converted the bit below on validation into a list to make it easier to understand.
3. The download is slightly revised (e168-assignment3-jgn-1.0.004.zip), and fixes two bugs. To fix the bugs by hand:
   1. In game_persister_file.rb, add a $ to the end of each regular expression that identifies Pylons or Players in the file. This is not the greatest fix, but it will do. Thus:

      if s =~ /pylon (.+?) '(.)' '(.)' ([\-\d]+?)\s+([\-\d]+?)$/
        # . . . . . .
      elsif s =~ /player (.+?) '(.)' '(.)' ([\-\d]+?)\s+([\-\d]+?)\s+([\-\d]+?)\s+([\-\d]+?)$/
      

      Thanks go to Ron.

   2. The other problem is more serious. In the Rakefile, remove this line from the package task:

      t.package_files.exclude("#{db_dir}migrate/**/*")
      

      Thanks go to Gabriel.

---

The purpose of this assignment is to give you some experience with ActiveRecord. You’ll define migrations for tables support ActiveRecord models, and run the migrations. You’ll be doing all of this “by hand.” When we get to Rails, you’ll see that there are a lot of convenient scripts and shortcuts for generating models and tables, but with AR, my experience has been: no pain, no gain. This is also why the schema for this assignment is very simple. As well, there are no tests. The problem with tests for “declarative” code (which is what much of ActiveRecord is), is that the tests reveal the solution.

There is a Firefox addon that allows for easy perusal of your database: I recommend that you install this addon: https://addons.mozilla.org/en-US/firefox/addon/5817

To do this assignment, download the ZIP (e168-assignment3-jgn-1.0.004.zip), and unzip it. Copy your student_solution.rb (and supporting files, if any) into the lib/world/ directory. Verify that your code works in this new context. We made some small changes which are documented in readme.rdoc. If your code doesn’t work, check it over very carefully; if it still doesn’t work, ZIP up your project for #3 and e-mail it directly to John.

What you are going to do is write a subclass of a new class called GamePersister. To give you the flavor of this, we provide a GamePersisterFile, which saves the state of the GameManager and any Pylons or Players to a text file. This is not the most elegant solution and is not very DRY, because we want the code to be as obvious as possible.

Now, if you’ve been reading the book and have been studying the Assignment 2 code, you may be thinking that we want to have the GameManager and Entity classes be ActiveRecord models. Or you may think that GameManager, Pylon, and Player ought to be models. We’re not going to do this. The reason is that to have Pylon be a model, we would have to subclass ActiveRecord::Base. But we are already committed to a class hierarchy. Therefore, we are going to create new models called SavedGame, SavedPylon, and SavedPlayer. The only reason our models for Pylons and Players have “Saved” in their names is to differentiate them from our existing classes. If you were were starting a project from scratch and knew that you were going to save data to a database, you might very well have subclassed ActiveRecord::Base from the start. [If we use this assignment next year, we'll handle the persistence with modules. But that requires changes to the core classes that we don't want to make at this time.]

Here’s a diagram of the tables/models you must implement:

(click to see larger version)

The “crow’s feet” (http://en.wikipedia.org/wiki/Entity-relationship_diagram#Crow.27s_Foot) in the lines between saved_games and saved_players and between saved_games and saved_pylons indicates which item refers to the other. In this case, the foreign keys are on saved_players and saved_pylons. This means that a SavedPlayer (and a SavedPylon) “belong to” a SavedGame. In reverse, Each SavedGame “has many” SavedPlayers and SavedPylons. As you get into this, you should review carefully the naming, case, and pluralization conventions used in code for ActiveRecord tables, models, and association names (in AWDR, see section 17.1, 18.3, and elsewhere; with regarding to associations, you want to watch for language such as this, in 18.3: “The parent class name is assumed to be the mixed-case singular form of the attribute name, and the foreign key field is the lowercase singular form of the parent class name with _id appended.” What this means is that in the SavedPlayer class, you would write “belongs_to :saved_game”, while in the database, the foreign key is going to be saved_game_id).

Now, because the GameManager manages a Pylon (for instance), but our ActiveRecord class is called a SavedPylon, we need some code that can add a Pylon to a GameManager based on the data in a SavedPylon. We have supplied code that will do this in GamePersister. For example:

# Add a SavedPylon to a GameManager
 def add_saved_pylon(game_manager, saved_pylon)
# Remember that a class name is just a constant.
#   game_manager.class.const_get(name) means:
# Find the constant with the given name, as the GameManager's class
# would understand that constant name. So, for instance, if the
# name is ShyPlayer, we will get the constant: ShyPlayer
# Now we can call .new on the constant (that is, on the class)
pylon = game_manager.class.const_get(saved_pylon.class_name).new(game_manager, saved_pylon.x, saved_pylon.y)
pylon.identity = saved_pylon.identity
pylon.appearance = saved_pylon.appearance
 end

There is a similar method to add a SavedPlayer, and there are a couple more methods to add collections of SavedPylons or SavedPlayers.

Another aspect of this that is a bit tricky is that when a SavedPylon or SavedPlayer is saved to the database, we include the class name of the Pylon or Player. So, when we get a SavedPylon out of the database, and want to “new” an appropriate Pylon, we have to utilize that saved class name. See the comments in the quoted code above for how we do this. Arguably, someone might use ActiveRecord’s “single table inheritance”feature to make this happen.

So, here’s what you have to do:

1. Define migrations in db/migrate to create the saved_games, saved_pylons, and saved_players tables. The attributes must be as given in the diagram above. For the foreign key columns, use the “references” method. In your migrations, you must ensure that none of the column values may be null.
2. Define ActiveRecord models for SavedGame, SavedPylon, and SavedPlayer. Please put these in the root of the lib/ directory. They should not be in any module.
3. Once you have the models, define the appropriate validations and associations (has_many, belongs_to, etc. You must decide on the associations that make sense with the diagram). For associations and validations:
   1. when a SavedGame is destroyed, any associated SavedPylons or SavedPlayers should also be destroyed automatically (hint: this requires a modifier on the associations);
   2. the name of each game must be unique;
   3. all non-key attributes, except appearance and identity, must not be “empty”;
   4. the identity and appearance attributes must have length 1;
   5. all non-key attributes that are supposed to be numbers must be validated for numericality, and must only be integers;
   6. the tick number of a SavedGame must be greater than or equal to 0.

   The reason appearance and identity are excluded from the the requirement that attributes be non-empty is because they can be a single space. The Validators consider a single space to be “empty,” so we have to handle them a bit differently.

   Everything up to this point should be pretty easy. We will give a lot of credit for a perfect job on the steps above.

4. Implement GamePersisterRdb. This should have the same behavior as GamePersisterFile (except that the data is stored to the database).
5. For this assignment, no writeup is required. If you have notes you want to add, you may, though, put them in readme-student.txt

To load and save games, use example_game_persistent.rb. If you add “rdb” to the command line, it will use the rdb persister; otherwise it will use the file persister:

# uses the file persister
ruby example_game_persistent.rb

# uses the rdb persister
ruby example_game_persistent.rb rdb

For the “file” version, we added a sample game (called “sample.game”). When you enter the game name, leave off the “.game” part.

Questions and Answers:

1. Q: I added some attributes to my own Pylons and Players, so they don’t get saved or loaded properly.
   A: Saving such Pylons and Players is out-of-scope. There is a fairly reasonable strategy to save Pylons and Players with extra attributes: Keep an eye on the lectures for the “serialize” method for ActiveRecord.
2. Q: It looks like there’s an opportunity to “share” Pylons and Players across games if they have exactly the same attributes. Should we check if a Pylon or Player is already in the database?
   A: No. The foreign key “saved_game_id” can only point to own game. To do what you’re talking about would require a “join table” in the middle, so as to support has_many :through.
3. Q: It seems as though there are opportunities for further validations. For example, I could require that the SavedGame’s x_min is less than its x_max; I could require that all SavedPylons and SavedPlayers are within their game boards.
   A: I would advise not doing that. Since the domain code is not too finicky about these details (except that it will cause exceptions to be raised!) it would be premature to lock down such details for the models.
4. Q: Are there any additional docs (compared to Assignment 2)?
   A: No.