Package: OthelloField

OthelloField

Coverage

1: /*
2: * Copyright © 2020 Fachhochschule für die Wirtschaft (FHDW) Hannover
3: *
4: * This file is part of othello-core.
5: *
6: * Othello-core is free software: you can redistribute it and/or modify
7: * it under the terms of the GNU General Public License as published by
8: * the Free Software Foundation, either version 3 of the License, or
9: * (at your option) any later version.
10: *
11: * Othello-core is distributed in the hope that it will be useful,
12: * but WITHOUT ANY WARRANTY; without even the implied warranty of
13: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14: * GNU General Public License for more details.
15: *
16: * You should have received a copy of the GNU General Public License
17: * along with othello-core. If not, see <http://www.gnu.org/licenses/>.
18: */
19: package de.fhdw.gaming.othello.core.domain;
20:
21: import java.util.Set;
22:
23: import de.fhdw.gaming.core.domain.GameException;
24:
25: /**
26: * Represents a single field on a {@link OthelloBoard board}.
27: * <p>
28: * A field has a {@link OthelloPosition position}. This position is fixed and does not change.
29: * <p>
30: * A field has a {@link OthelloFieldState state}. The state may change, but only the following state transitions are
31: * allowed:
32: * <ul>
33: * <li>{@link OthelloFieldState#EMPTY EMPTY} -> {@link OthelloFieldState#BLACK BLACK}</li>
34: * <li>{@link OthelloFieldState#EMPTY EMPTY} -> {@link OthelloFieldState#WHITE WHITE}</li>
35: * <li>{@link OthelloFieldState#WHITE WHITE}-> {@link OthelloFieldState#BLACK BLACK}</li>
36: * <li>{@link OthelloFieldState#BLACK BLACK} -> {@link OthelloFieldState#WHITE WHITE}</li>
37: * </ul>
38: * In other words, a non-empty field may never become empty again.
39: * <p>
40: * The state of a field cannot be changed directly. Instead, a conforming move has to be submitted to the rule engine.
41: */
42: public interface OthelloField {
43:
44: /**
45: * Returns the board this field belongs to.
46: */
47: OthelloBoard getBoard();
48:
49: /**
50: * Returns the position of this field.
51: */
52: OthelloPosition getPosition();
53:
54: /**
55: * Returns the current state of this field.
56: */
57: OthelloFieldState getState();
58:
59: /**
60: * Determines whether there is a neighbour field in a given direction.
61: *
62: * @param direction The direction to use.
63: * @return {@code true} if there is a neighbour field in the given direction, otherwise {@code false}.
64: */
65: boolean hasNeighbour(OthelloDirection direction);
66:
67: /**
68: * Returns a neighbour field in a given direction.
69: *
70: * @param direction The direction to use.
71: * @return The corresponding neighbour field.
72: * @throws IllegalArgumentException if there is no neighbour field in the given direction.
73: */
74: OthelloField getNeighbour(OthelloDirection direction) throws IllegalArgumentException;
75:
76: /**
77: * Determines whether this is an active field for placing a token of the given colour. For this to be true, this
78: * field needs to be {@link OthelloFieldState#EMPTY empty}, and it has to start at least one continuous line of
79: * tokens of the other colour, delimited by a token of the same colour.
80: *
81: * @param placingBlackToken {@code true} if checking for an active black field, and {@code false} if checking for an
82: * active white field.
83: * @return {@code true} if this is an active field for the given colour, else {@code false}.
84: */
85: boolean isActive(boolean placingBlackToken);
86:
87: /**
88: * Determines whether there is a line of tokens in the given direction that could be enclosed by a token.
89: *
90: * @param direction The direction.
91: * @param delimiterState The state of the field delimiting the line of tokens.
92: * @return The fields containing the tokens in the line (excluding this field and the delimiting field). This is
93: * always a valid set, but may be empty if no line of tokens could be found in the given direction. Note
94: * that the set returned is not necessarily mutable.
95: */
96: Set<? extends OthelloField> getLineOfTokens(OthelloDirection direction, OthelloFieldState delimiterState);
97:
98: /**
99: * Places a token on this field. Requires this field to be active. Computes and changes the state of neighbour
100: * fields according to the rules of the game.
101: *
102: * @param blackToken {@code true} if a black token is placed, and {@code false} if a white token is placed.
103: * @throws GameException if placing a token of the given colour is not allowed according to the rules of the game.
104: */
105: void placeToken(boolean blackToken) throws GameException;
106: }