Package edu.wisc.game.sql

## Class PlayerInfo

- java.lang.Object
- - edu.wisc.game.sql.PlayerInfo

-     @Entity
      public class PlayerInfo
      extends Object

  Information about a player (what trial list he's in, what episodes he's done etc) stored in the SQL database.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `PlayerInfo.Action` | What type of action takes the player to a particular destination?
    `static class` | `PlayerInfo.Transition` | Where can we go from here?
    `class` | `PlayerInfo.TransitionMap` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `PlayerInfo()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `activateBonus​(javax.persistence.EntityManager em)` | Switches this player from the main subseries to the bonus subseries, and saves the information about this fact in the SQL server.
    `void` | `addEpisode​(EpisodeInfo c)` |
    `boolean` | `alreadyFinished()` | Returns true if the current series number is set beyond the possible range, which indicates that it has gone through the last possible increment (and, therefore, the completion code has been set as well).
    `static String` | `assignTrialList​(String player)` |
    `boolean` | `canActivateBonus()` |
    `int` | `countBonusEpisodes​(int k)` | How many bonus episodes (complete or not) are currently in series No.
    `EpisodeInfo` | `episodeToDo()` | Returns the currently unfinished last episode to be resumed, or a new episode (in the current series or the next series, as the case may be), or null if this player has finished with all series.
    `Vector<EpisodeInfo>` | `getAllEpisodes()` |
    `String` | `getCompletionCode()` | The completion code, a string that the player can report as a proof of his completion of the experiment plan.
    `int` | `getCurrentSeriesNo()` |
    `Date` | `getDate()` |
    `String` | `getExperimentPlan()` |
    `ParaSet` | `getPara​(EpisodeInfo epi)` | Gives a link to the ParaSet associated with a given episode
    `String` | `getPlayerId()` |
    `int` | `getTotalRewardEarned()` |
    `String` | `getTrialListId()` |
    `void` | `giveUp​(int seriesNo)` | "Gives up" he current series, i.e.
    `void` | `initSeries​(TrialList trialList)` | This is usesd when a player is first registered and a PlayerInfo object is first created
    `EpisodeInfo` | `mostRecentEpisode()` | Retrieves the most recent episode, which may be completed or incomplete.
    `void` | `removeEpisode​(EpisodeInfo c)` |
    `String` | `report()` | Generates a concise report on this player's history, handy for debugging.
    `void` | `restoreTransientFields()` | This method should be called after restoring the object from the SQL database, in order to re-create some of the necessary non-persistent structures.
    `void` | `saveMe()` | Saves this object (and the associated Episode objects, via cascading) data in the SQL database.
    `int` | `seriesSize​(int k)` | How many episodes are currently in series No.
    `void` | `setAllEpisodes​(Vector<EpisodeInfo> _allEpisodes)` |
    `void` | `setCompletionCode​(String _completionCode)` |
    `void` | `setDate​(Date _date)` |
    `void` | `setExperimentPlan​(String _experimentPlan)` |
    `void` | `setPlayerId​(String _playerId)` |
    `void` | `setTotalRewardEarned​(int _totalRewardEarned)` |
    `void` | `setTrialListId​(String _trialListId)` |
    `String` | `toString()` |

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### PlayerInfo

          public PlayerInfo()

  - ### Method Detail

    - #### getPlayerId

          public String getPlayerId()

    - #### setPlayerId

          public void setPlayerId​(String _playerId)

    - #### getExperimentPlan

          public String getExperimentPlan()

    - #### setExperimentPlan

          public void setExperimentPlan​(String _experimentPlan)

    - #### getTrialListId

          public String getTrialListId()

    - #### setTrialListId

          public void setTrialListId​(String _trialListId)

    - #### getDate

          public Date getDate()

    - #### setDate

          public void setDate​(Date _date)

    - #### addEpisode

          public void addEpisode​(EpisodeInfo c)

    - #### removeEpisode

          public void removeEpisode​(EpisodeInfo c)

    - #### getAllEpisodes

          public Vector<EpisodeInfo> getAllEpisodes()

    - #### setAllEpisodes

          public void setAllEpisodes​(Vector<EpisodeInfo> _allEpisodes)

    - #### assignTrialList

          public static String assignTrialList​(String player)

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### alreadyFinished

          public boolean alreadyFinished()

      Returns true if the current series number is set beyond the possible range, which indicates that it has gone through the last possible increment (and, therefore, the completion code has been set as well).

    - #### canActivateBonus

          public boolean canActivateBonus()

      Returns:
        true if an "Activate Bonus" button can be displayed, i.e. the player is eligible to start bonus episodes, but has not done that yet

    - #### activateBonus

          public void activateBonus​(javax.persistence.EntityManager em)

      Switches this player from the main subseries to the bonus subseries, and saves the information about this fact in the SQL server.
      Parameters:
        `em` - The active EM to use. (We have this because this method is called from a method that has an EM anyway, and this object is NOT detached.)

    - #### giveUp

          public void giveUp​(int seriesNo)
                      throws IOException

      "Gives up" he current series, i.e. immediately switches the player to the next series (if there is one).
      Throws:
        `IOException`

    - #### seriesSize

          public int seriesSize​(int k)

      How many episodes are currently in series No. k?

    - #### countBonusEpisodes

          public int countBonusEpisodes​(int k)

      How many bonus episodes (complete or not) are currently in series No. k?

    - #### getCurrentSeriesNo

          public int getCurrentSeriesNo()

    - #### initSeries

          public void initSeries​(TrialList trialList)
                          throws IOException,
                                 IllegalInputException,
                                 ReflectiveOperationException,
                                 RuleParseException

      This is usesd when a player is first registered and a PlayerInfo object is first created
      Throws:
        `IOException`
        `IllegalInputException`
        `ReflectiveOperationException`
        `RuleParseException`

    - #### restoreTransientFields

          public void restoreTransientFields()
                                      throws IOException,
                                             IllegalInputException,
                                             ReflectiveOperationException,
                                             RuleParseException

      This method should be called after restoring the object from the SQL database, in order to re-create some of the necessary non-persistent structures. Typically, this may be needed if player resumes his activity after the Game Server has been restarted. In particular, we restore the "series" structure, reloading paramter sets from the disk files and and putting episodes in their series arrays.

      We also review the episodes, and "give up" all incomplete ones, because they don't have their transcripts and rules loaded, and cannot be continued. This may happen only rarely, when an episode had been persisted before beeing completed (thru cascading from the player being persisted), and then the server was restarted.

      Throws:
        `IOException`
        `IllegalInputException`
        `ReflectiveOperationException`
        `RuleParseException`

    - #### mostRecentEpisode

          public EpisodeInfo mostRecentEpisode()

      Retrieves the most recent episode, which may be completed or incomplete.

    - #### episodeToDo

          public EpisodeInfo episodeToDo()
                                  throws IOException,
                                         RuleParseException

      Returns the currently unfinished last episode to be resumed, or a new episode (in the current series or the next series, as the case may be), or null if this player has finished with all series. This is used by the /GameService2/newEpisode web API call.
      Throws:
        `IOException`
        `RuleParseException`

    - #### getPara

          public ParaSet getPara​(EpisodeInfo epi)

      Gives a link to the ParaSet associated with a given episode

    - #### getCompletionCode

          public String getCompletionCode()

      The completion code, a string that the player can report as a proof of his completion of the experiment plan. It is set when the current series number is incremented beyond the last parameter set number.

    - #### setCompletionCode

          public void setCompletionCode​(String _completionCode)

    - #### getTotalRewardEarned

          public int getTotalRewardEarned()

    - #### setTotalRewardEarned

          public void setTotalRewardEarned​(int _totalRewardEarned)

    - #### report

          public String report()

      Generates a concise report on this player's history, handy for debugging. It gives summaries of all episodes done (or in progress) by this player, broken down by series.

    - #### saveMe

          public void saveMe()

      Saves this object (and the associated Episode objects, via cascading) data in the SQL database. The assumption is that this object is detached, so we call a method which will create a new EM and merge this object to the new persistence context.