Package: TicTacToeField

TicTacToeField

Coverage

1: /*
2: * Copyright © 2021-2023 Fachhochschule für die Wirtschaft (FHDW) Hannover
3: *
4: * This file is part of ipspiel24-tictactoe-core.
5: *
6: * ipspiel24-tictactoe-core is free software: you can redistribute it and/or modify it under
7: * the terms of the GNU General Public License as published by the Free Software
8: * Foundation, either version 3 of the License, or (at your option) any later
9: * version.
10: *
11: * ipspiel24-tictactoe-core is distributed in the hope that it will be useful, but WITHOUT
12: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
13: * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
14: * details.
15: *
16: * You should have received a copy of the GNU General Public License along with
17: * ipspiel24-tictactoe-core. If not, see <http://www.gnu.org/licenses/>.
18: */
19: package de.fhdw.gaming.ipspiel24.tictactoe.core.domain;
20:
21: import de.fhdw.gaming.core.domain.GameException;
22:
23: /**
24: * Represents a single field on a {@link TicTacToeBoard board}.
25: * <p>
26: * A field has a {@link TicTacToePosition position}. This position is fixed and does not change.
27: * <p>
28: * A field has a {@link TicTacToeFieldState state}. The state may change, but only the following state transitions are
29: * allowed:
30: * <ul>
31: * <li>{@link TicTacToeFieldState#EMPTY EMPTY} -> {@link TicTacToeFieldState#CROSS CROSS}</li>
32: * <li>{@link TicTacToeFieldState#EMPTY EMPTY} -> {@link TicTacToeFieldState#NOUGHT NOUGHT}</li>
33: * </ul>
34: * In other words, a non-empty field may never change again.
35: * <p>
36: * The state of a field cannot be changed directly. Instead, a conforming move has to be submitted to the rule engine.
37: */
38: public interface TicTacToeField {
39:
40: /**
41: * Returns the board this field belongs to.
42: */
43: TicTacToeBoard getBoard();
44:
45: /**
46: * Returns the position of this field.
47: */
48: TicTacToePosition getPosition();
49:
50: /**
51: * Returns the current state of this field.
52: */
53: TicTacToeFieldState getState();
54:
55: /**
56: * Determines whether there is a neighbour field in a given direction.
57: *
58: * @param direction The direction to use.
59: * @return {@code true} if there is a neighbour field in the given direction, otherwise {@code false}.
60: */
61: boolean hasNeighbour(TicTacToeDirection direction);
62:
63: /**
64: * Returns a neighbour field in a given direction.
65: *
66: * @param direction The direction to use.
67: * @return The corresponding neighbour field.
68: * @throws IllegalArgumentException if there is no neighbour field in the given direction.
69: */
70: TicTacToeField getNeighbour(TicTacToeDirection direction) throws IllegalArgumentException;
71:
72: /**
73: * Changes the state of this field. Requires this field to be empty.
74: *
75: * @param state The new state of the field.
76: * @throws GameException if placing a token of the given type is not allowed according to the rules of the game.
77: */
78: void changeState(TicTacToeFieldState state) throws GameException;
79: }