View source for Herança e Composição/Exercício 04: Arabian Nights in Java

{{TOCright}}
= Problema =
		
Aplicando os conceitos OO que já conhece, concretize as classes necessárias para representar a funcionalidade que se descreve de seguida. Pode ser necessária a criação de classes adicionais não descritas abaixo. A correcta execução dos testes depende da estrita aderência à nomenclatura das classes apresentadas. Todas as classes indicadas devem pertencer à "package" '''arabiannights'''. 

== Funcionalidade da lâmpada mágica (classe "MagicLamp") ==

Uma lâmpada mágica liberta génios quando esfregada (método  rub). Os génios podem ser bem ou mal-humorados. O humor dos génios é determinado pelas condições da lâmpada: sempre que a lâmpada tiver sido esfregada um número par de vezes (sem contar a actual), o génio sai mal-humorado. A quantidade de génios disponíveis é determinada no momento de encantamento da lâmpada (criação). Depois de esgotados os génios disponíveis, já não adianta esfregar a lâmpada para obter um génio, bem ou mal-humorado: nestas condições, a lâmpada cria um pequeno demónio que responde a pedidos de forma literal mas perversa. Devido a requisitos de sustentabilidade ambiental, as normas de produção exigem que as lâmpadas sejam recarregáveis. Assim, é possível voltar a obter génios quando se esfrega a lâmpada (em número igual ao inicial). O processo de recarregamento exige apenas que um demónio seja alimentado à lâmpada (método '''feedDemon''').

Quando se cria uma nova lâmpada é necessário indicar a quantidade inicial de génios que é possível invocar. É possível saber quantos génios ainda estão disponíveis na lâmpada (método '''getGenies'''). É ainda possível saber quantas vezes a lâmpada já foi recarregada (método '''getDemons'''). Quando se esfrega a lâmpada, deve-se indicar quantos desejos se espera que o génio realize (independentemente de o génio os poder negar). 

A classe '''MagicLamp''' deve saber comparar as suas instâncias (através do método '''equals'''). Considera-se que duas lâmpadas são iguais se tiverem a mesma capacidade e se os valores retornados pelos métodos '''getGenies''' e '''getDemons''' forem iguais.

Nota: a lâmpada liberta apenas um génio de cada vez.

== Funcionalidade do génio bem-humorado (classe "FriendlyGenie") ==

O génio bem-humorado concede todos os desejos que lhe forem colocados (método '''grantWish''' e retorno '''true'''), até ao limite com que foi chamado da lâmpada. Depois do limite já não são concedidos desejos (retorno '''false'''). É possível saber quantos desejos já foram concedidos (método '''getGrantedWishes''') e quantos ainda existem disponíveis (método '''getRemainingWishes''').

Nota: o génio concede apenas um desejo de cada vez.

== Funcionalidade do génio mal-humorado (classe "GrumpyGenie") ==

O génio mal-humorado concede apenas o primeiro desejo que lhe for colocado (método '''grantWish''' e retorno '''true'''), independentemente do limite com que foi chamado da lâmpada (retorno '''false''' após o primeiro). É possível saber se o desejo já foi realizado (método '''getGrantedWishes''' retorna 1).

== Funcionalidade do demónio reciclável (classe "RecyclableDemon") ==

O demónio concede todos os desejos que lhe forem colocados (método '''grantWish''' e retorno '''true'''), independentemente do limite com que foi chamado da lâmpada. Se o demónio for recolocado na lâmpada (para a recarregar), já não pode realizar mais desejos (retorno '''false'''). É possível saber quantos desejos já foram concedidos (método '''getGrantedWishes''').

Nota: o demónio concede apenas um desejo de cada vez.

== Observações ==

Todas as classes devem ter métodos de acesso (''get'' e ''set'') (quando apropriado) para os seus atributos. 

O método '''toString''', aplicado aos génios e ao demónio, deve devolver uma das seguintes cadeias de caracteres: 
* <tt>Friendly genie has granted # wishes and still has # to grant.</tt> (os # representam os contadores apropriados)
* <tt>Grumpy genie has granted a wish.</tt>  (se já concedeu o pedido)
* <tt>Grumpy genie has a wish to grant.</tt> (se ainda não concedeu o pedido)
* <tt>Recyclable demon has granted # wishes.</tt> (antes de recarregar uma lâmpada)
* <tt>Demon has been recycled.</tt> (depois de recarregar uma lâmpada)

A classe cliente, de nome '''ArabianNights''' deve possuir um método (static) '''main''' que execute a seguinte sequência de operações:
# Criar uma lâmpada mágica com capacidade para 4 génios.
# Esfregar 5 vezes a lâmpada, indicando os números de desejos 2, 3, 4, 5, 1.
# Invocar e imprimir o resultado do método '''toString''' sobre cada um dos génios.
# Pedir um desejo a cada um dos génios.
# Invocar e imprimir o resultado do método '''toString''' sobre cada um dos génios.
# Pedir um desejo a cada um dos génios.
# Invocar e imprimir o resultado do método '''toString''' sobre cada um dos génios.
# Colocar o demónio reciclável na lâmpada.
# Esfregar a lâmpada, indicando 7 como número de desejos.
# Invocar e imprimir o resultado do método '''toString''' sobre o génio obtido.

= Solution =

The following corresponds to a possible telling of a special version of the Arabian Nights stories. In any implementation, the following concepts will exist in one form or another: MagicLamp, Genie (a general type of genie, which may also describe the recyclable demon), FriendlyGenie, GrumpyGenie, and RecyclableDemon. 

== UML Class Diagram ==

{{CollapsedCode|Diagrama de classes|
[[Image:PO-ArabianNights-Java-1.png]]
}}

== Class MagicLamp ==

{{CollapsedCode|Ficheiro '''MagicLamp.java'''|
<source lang="java" line>
package arabiannights;

public class MagicLamp {

	/**
	 * Maximum number of wishes (does not mean that the genie will grant them all).
	 */
	private int _limit;

	/** Total number of rubs. */
	private int _totalRubs;

	/** Number of rubs since last charge. */
	private int _rubs;

	/** Number of recharges. */
	private int _demons;

	/**
	 * @param limit
	 *            how many genies can come out.
	 */
	public MagicLamp(int limit) {
		_limit = limit;
	}

	/**
	 * @return the maximum number of genies.
	 */
	public int getLimit() {
		return _limit;
	}

	/**
	 * @return how many times it was rubbed since last change.
	 */
	public int getRubs() {
		return _rubs;
	}

	/**
	 * @return total number of rubs.
	 */
	public int getTotalRubs() {
		return _totalRubs;
	}

	/**
	 * @return number of available genies.
	 */
	public int getGenies() {
		return getLimit() - getRubs();
	}

	/**
	 * @return number of demons.
	 */
	public int getDemons() {
		return _demons;
	}

	/**
	 * Ask the lamp for a genie. If the number of rubs is even, return a grumpy
	 * genie. If the number of rubs is more than the limit, return a demon.
	 * Otherwise, return a normal friendly genie.
	 * 
	 * @param wishes
	 *            maximum number of wishes the genie is able to grant (may not
	 *            be the actual number of granted wishes).
	 * 
	 * @return a genie.
	 */
	public Genie rub(int wishes) {
		if (_rubs < _limit) {
			_rubs++;
			_totalRubs++;
			if (_totalRubs % 2 == 0)
				return new FriendlyGenie(wishes);
			return new GrumpyGenie(wishes);
		}
		return new RecyclableDemon(wishes);
	}

	/**
	 * Recharge the magic lamp by feeding it a demon. A demon can only be used
	 * if not previously recycled.
	 * 
	 * @param demon
	 *            the recyclable demon.
	 */
	public void feedDemon(RecyclableDemon demon) {
		if (!demon.recycled()) {
			demon.recycle();
			_rubs = 0;
			_demons++;
		}
	}

	/**
	 * This is the default equality method inherited from class Object.
	 * 
	 * @see java.lang.Object#equals(java.lang.Object)
	 */
	@Override
	public boolean equals(Object o) {
		return o instanceof MagicLamp && equals((MagicLamp) o);
	}

	/**
	 * This is a local method (i.e., NOT INHERITED) that is only able to compare
	 * this lamp with another.
	 * 
	 * @return true if, in addition to the same capacity, the number of
	 *         available genies and the number of recharges are the same; false,
	 *         otherwise.
	 */
	public boolean equals(MagicLamp l) {
		return getLimit() == l.getLimit() && getGenies() == l.getGenies()
				&& getDemons() == l.getDemons();
	}

}
</source>
}}

== Class Genie ==

Class Genie defines the basic behaviour for all genies.

Note that, since Genie is a class whose methods are to be redefined by subclasses and whose references will only point to subclass instances.

{{CollapsedCode|Ficheiro '''Genie.java'''|
<source lang="java" line>
package arabiannights;

/**
 * General genie. Grants a number of wishes under certain conditions.
 */
public abstract class Genie {

	/**
	 * Maximum number of wishes (does not mean that the genie will grant them all).
	 */
	private int _limit;

	/** Number of wishes granted. */
	private int _granted;

	/**
	 * @param limit the maximum number of wishes to grant.
	 */
	protected Genie(int limit) {
		_limit = limit;
	}

	/**
	 * @return the maximum number of wishes.
	 */
	public int getLimit() {
		return _limit;
	}

	/**
	 * @return the number of wishes already granted.
	 */
	public int getGrantedWishes() {
		return _granted;
	}

	/**
	 * Increment wish counter.
	 */
	public void incrementGranted() {
		_granted++;
	}

	/**
	 * Ask the genie to grant a wish. Never allow more grants than the initial limit.
	 * 
	 * @return true if the wish is granted; false otherwise.
	 */
	public boolean grantWish() {
		if (canGrantWish()) {
			incrementGranted();
			doGrantWish();
			return true;
		}
		return false;
	}

	/**
	 * Decide if genie can grant a wish.
	 * 
	 * @return true or false (depends on special circumstances).
	 */
	public boolean canGrantWish() {
		return _granted < _limit;
	}

	/**
	 * Do actual wish granting. By default, does not do anything. Subclasses
	 * will do something specific.
	 */
	public void doGrantWish() {
		// NOTHING TO DO
	}

}
</source>
}}

==  Class FriendlyGenie ==

A friendly genie is almost like a general genie (it differs in the output messages).

{{CollapsedCode|Ficheiro '''FriendlyGenie.java'''|
<source lang="java" line>
package arabiannights;

/**
 * A friendly genie is actually a normal genie, but with special descriptive text.
 */
public class FriendlyGenie extends Genie {

	/**
	 * @param limit
	 *            the maximum number of wishes to grant.
	 */
	public FriendlyGenie(int limit) {
		super(limit);
	}

	/**
	 * @return the number of wishes left to grant.
	 */
	public int getRemainingWishes() {
		return getLimit() - getGrantedWishes();
	}

	/**
	 * @see java.lang.Object#toString()
	 */
	@Override
	public String toString() {
		return "Friendly genie has granted " + getGrantedWishes() + " wishes and still has "
				+ getRemainingWishes() + " to grant.";
	}

}
</source>
}}

==  Class GrumpyGenie ==

Redefines a few methods.

{{CollapsedCode|Ficheiro '''GrumpyGenie.java'''|
<source lang="java" line>
package arabiannights;

/**
 * Behaves like any other genie, but with some differences (only one wish).
 */
public class GrumpyGenie extends Genie {

	/**
	 * @param limit
	 *            the number of wishes to grant (ignored: always grants only one wish).
	 */
	public GrumpyGenie(int limit) {
		super(1);
	}

	/**
	 * @see java.lang.Object#toString()
	 */
	@Override
	public String toString() {
		return (getGrantedWishes() == 1) ? "Grumpy genie has granted a wish."
				: "Grumpy genie has a wish to grant.";
	}

}
</source>
}}

== Class RecyclableDemon ==

The RecyclableDemon is a genie that implements some of the control methods in a special way (but still adheres to the template method defined by class Genie).

{{CollapsedCode|Ficheiro '''RecyclableDemon.java'''|
<source lang="java" line>
package arabiannights;

/**
 * Recyclable demon.
 */
public class RecyclableDemon extends Genie {

	/** Has been recycled? */
	private boolean _recycled = false;

	/**
	 * @param limit
	 *            the number of wishes to grant (ignored: always grants wishes).
	 */
	public RecyclableDemon(int limit) {
		super(limit);
	}

	/**
	 * Recyclable demons always grant wishes (unless they have been recycled).
	 * 
	 * @return true if not yet recycled; false, otherwise.
	 */
	@Override
	public boolean canGrantWish() {
		return !_recycled;
	}

	/**
	 * @return whether a demon has been recycled.
	 */
	public boolean recycled() {
		return _recycled;
	}

	/**
	 * Recycle a demon (called by a magic lamp).
	 */
	public void recycle() {
		_recycled = true;
	}

	/**
	 * @see java.lang.Object#toString()
	 */
	@Override
	public String toString() {
		return _recycled ? "Demon has been recycled." : "Recyclable demon has granted "
				+ getGrantedWishes() + " wishes.";
	}

}
</source>
}}

==  The Application ==

In this case, the main class is straightforward.

Numbers in comments correspond to the specified steps in the problem above.

{{CollapsedCode|Ficheiro '''ArabianNights.java'''|
<source lang="java" line>
import arabiannights.*;

/**
 * The application class (main function).
 */
public class ArabianNights {

	/**
	 * @param args command line arguments.
	 */
	public static void main(String args[]) {

		/* 01 */ MagicLamp m = new MagicLamp(4);
		/* 02 */ Genie gv[] = { m.rub(2), m.rub(3), m.rub(4), m.rub(5), m.rub(1) };
		/* 03 */ for (Genie g : gv) System.out.println(g);
		
		System.out.println("======================");
		
		/* 04 */ for (Genie g : gv) g.grantWish();
		/* 05 */ for (Genie g : gv) System.out.println(g);
		
		System.out.println("======================");
		
		/* 06 */ for (Genie g : gv) g.grantWish();
		/* 07 */ for (Genie g : gv) System.out.println(g);
		
		System.out.println("======================");
		
		// recyclable demon is the last one in the array
		/* 08 */ m.feedDemon((RecyclableDemon) gv[4]);
		/* 09 */ Genie g = m.rub(7);
		/* 10 */ System.out.println(g);
		
		System.out.println("======================");

	}

}
</source>
}}

= Compiling and Running =

== How to Compile? ==

The compilation is as follows: 

 javac arabiannights/MagicLamp.java
 javac arabiannights/Genie.java
 javac arabiannights/FriendlyGenie.java
 javac arabiannights/GrumpyGenie.java
 javac arabiannights/RecyclableDemon.java
 javac ArabianNights.java

In fact, compiling ArabianNights.java would cause the rest of them be compiled as well (the Java compiler accounts for all explicit class dependencies). 

We assume that the CLASSPATH environment variable contains the current directory

== Running ==

The program starts at a '''main''' function (in this case, contained in the '''ArabianNights''' class): 

 java ArabianNights

= See Also =

* [[Arabian Nights in C++]]

[[category:Ensino]]
[[category:PO]]
[[category:PO Exemplos]]