inonit.domain.game.card.hearts
Interface Intelligence

All Known Implementing Classes:
AbstractIntelligence

public interface Intelligence

An object capable of playing Hearts.

Intelligence methods which return values are required to return valid values, and are required not to throw exceptions. In the event that they do return illegal values or throw exceptions, the server will make random legal plays on their behalf.

It may be more convenient to subclass AbstractIntelligence than to implement Intelligence directly. AbstractIntelligence provides a simple world-state, and its interface may be more stable than Intelligence's in early versions of Hearts.

Relative Index

Many methods in Intelligence and its related objects have int index arguments representing players in the game. From the point of view of an Intelligence, it is always index 0. The player to its left is player 1, and so on.


Inner Class Summary
static interface Intelligence.Environment
          An object which can provide an Intelligence with services from, or information about, the environment in which it is running.
static interface Intelligence.Game
          An object which can provide information to Intelligences about a game in which they are participating.
static interface Intelligence.Hand
          An object which can provide information to Intelligence objects about a hand in which they are participating.
static interface Intelligence.Kitty
          An object representing a "kitty" -- a set of leftover cards which is distributed to one of the players in a game in which the deck is not evenly divisible among the players.
static interface Intelligence.Pass
          An object containing information about a particular set of cards that was passed.
static interface Intelligence.Play
          An object representing a card played.
static interface Intelligence.Trick
          An object representing a trick in which this Intelligence is participating.
 
Field Summary
static Intelligence RANDOM
          An Intelligence implementation which plays randomly.
 
Method Summary
 void cardPlayed(Intelligence.Play play)
          Informs this Intelligence that a card has been played.
 void destroy()
          Informs this Intelligence that it is about to be destroyed.
 void exceptionThrown(java.lang.String stackTrace)
          Informs this Intelligence that an exception was thrown from one of its methods (other than getPass or getPlay; an Intelligence is informed of exceptions from these methods via passIgnored and playIgnored, respectively); may be useful for debugging.
 void gameEnded()
          Informs this Intelligence that the game in which it was participating has ended.
 void gameStarting(Intelligence.Game game)
          Informs this Intelligence that a game is starting, and provides a Game object representing the current game.
 CardArray getPass()
          Invoked to ask this Intelligence for Cards to pass to another player.
 Card getPlay()
          Invoked to ask this Intelligence to play a Card.
 void handEnded()
          Informs this Intelligence that the current hand has ended.
 void handStarting(Intelligence.Hand hand)
          Informs this Intelligence that a hand has been dealt, and provides it with a Intelligence.Hand object representing the current hand.
 void initialize(Intelligence.Environment environment)
          Informs this Intelligence that it has been instantiated, and provides it with an Environment from which it can obtain various services.
 void kittyTaken(Intelligence.Kitty kitty)
          Informs this Intelligence that a player has taken the kitty for this hand.
 void passIgnored(java.lang.String reason)
          Informs this Intelligence that the result of getPass was not used, including a String message describing why.
 void playIgnored(java.lang.String reason)
          Informs this Intelligence that the result of getPlay was not used, including a String message describing why.
 void receivedPass(Intelligence.Pass pass)
          Informs this Intelligence that it has received cards from another player.
 void sentPass(Intelligence.Pass pass)
          Informs this Intelligence that it has passed cards to another player.
 void trickEnded()
          Informs this Intelligence that the current trick has ended.
 void trickStarting(Intelligence.Trick trick)
          Informs this Intelligence that a trick is about to start, and provides it with a Intelligence.Trick object representing the current trick.
 

Field Detail

RANDOM

public static final Intelligence RANDOM
An Intelligence implementation which plays randomly.
Method Detail

initialize

public void initialize(Intelligence.Environment environment)
Informs this Intelligence that it has been instantiated, and provides it with an Environment from which it can obtain various services.
Parameters:
environment - An Intelligence.Environment representing external information and services.

gameStarting

public void gameStarting(Intelligence.Game game)
Informs this Intelligence that a game is starting, and provides a Game object representing the current game.
Parameters:
game - An Intelligence.Game object containing information about the game which is starting.

handStarting

public void handStarting(Intelligence.Hand hand)
Informs this Intelligence that a hand has been dealt, and provides it with a Intelligence.Hand object representing the current hand.
Parameters:
hand - A Intelligence.Hand containing information about the current hand, including the cards dealt to this Intelligence.

sentPass

public void sentPass(Intelligence.Pass pass)
Informs this Intelligence that it has passed cards to another player.
Parameters:
pass - A Pass object containing information about what was passed, and to whom. Ordinarily, what was passed will already be known by this Intelligence, unless it timed out trying to pass or returned an invalid pass from getPass.

receivedPass

public void receivedPass(Intelligence.Pass pass)
Informs this Intelligence that it has received cards from another player.
Parameters:
pass - A Pass object containing information about what was received, and from whom.

trickStarting

public void trickStarting(Intelligence.Trick trick)
Informs this Intelligence that a trick is about to start, and provides it with a Intelligence.Trick object representing the current trick.
Parameters:
trick - A Trick object which can provide information about the current trick.

cardPlayed

public void cardPlayed(Intelligence.Play play)
Informs this Intelligence that a card has been played. Note that this method will be invoked even for cards played by itself.
Parameters:
play - A Intelligence.Play object containing information about who played the card, and what was played.

trickEnded

public void trickEnded()
Informs this Intelligence that the current trick has ended.

kittyTaken

public void kittyTaken(Intelligence.Kitty kitty)
Informs this Intelligence that a player has taken the kitty for this hand.
Parameters:
kitty - A Kitty object containing information about the kitty.

handEnded

public void handEnded()
Informs this Intelligence that the current hand has ended.

gameEnded

public void gameEnded()
Informs this Intelligence that the game in which it was participating has ended. Since Intelligence objects can participate in more than one game (sequentially), any game-specific information should be cleared in this method.

destroy

public void destroy()
Informs this Intelligence that it is about to be destroyed. Intelligence objects have a last opportunity to clean up during this method.

getPass

public CardArray getPass()
Invoked to ask this Intelligence for Cards to pass to another player. Should return a CardArray containing the Cards from this Intelligence's hand which it wishes to pass.

Whether this method is invoked in hands which are hold hands -- i.e., hands in which the Intelligence would be passing to itself -- is unspecified.

If this method does not successfully return a valid pass, the following steps will take place:

Returns:
A CardArray containing the Cards which it wishes to pass. Must not be null. Must contain the number of Cards specified by size. Must contain Cards that were dealt to the Intelligence in handStarting.

getPlay

public Card getPlay()
Invoked to ask this Intelligence to play a Card. Should return a Card that this Intelligence wishes to play.

If this method does not successfully return a valid play, the following steps will take place:

Returns:
A Card that this Intelligence wishes to play. Must not be null. Must be a Card in this Intelligence's hand.

passIgnored

public void passIgnored(java.lang.String reason)
Informs this Intelligence that the result of getPass was not used, including a String message describing why.
Parameters:
reason - A String describing why getPass() was ignored.

playIgnored

public void playIgnored(java.lang.String reason)
Informs this Intelligence that the result of getPlay was not used, including a String message describing why.
Parameters:
reason - A String describing why getPlay() was ignored.

exceptionThrown

public void exceptionThrown(java.lang.String stackTrace)
Informs this Intelligence that an exception was thrown from one of its methods (other than getPass or getPlay; an Intelligence is informed of exceptions from these methods via passIgnored and playIgnored, respectively); may be useful for debugging.
Parameters:
stackTrace - A String containing the exception's stack trace.