Package: InputProvider

InputProvider

Coverage

1: /*
2: * Copyright © 2020 Fachhochschule für die Wirtschaft (FHDW) Hannover
3: *
4: * This file is part of gaming-core.
5: *
6: * Gaming-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: * Gaming-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: * gaming-core. If not, see <http://www.gnu.org/licenses/>.
18: */
19: package de.fhdw.gaming.core.ui;
20:
21: import java.util.List;
22: import java.util.Map;
23: import java.util.Optional;
24: import java.util.Set;
25:
26: import de.fhdw.gaming.core.ui.type.validator.Validator;
27:
28: /**
29: * Provides user input by creating a dialogue with the user. First, a sequence of fields is described, then the contents
30: * of these fields are requested from the user. The form of presentation is decided by the concrete implementation. For
31: * example, this may be done by prompting the fields one after another on the text console, or by showing a GUI dialog
32: * where the user may type the data in arbitrary order and submit all data at once.
33: */
34: public interface InputProvider {
35:
36: /**
37: * Indicates the need for a string value from the user.
38: *
39: * @param id The ID of the field.
40: * @param prompt The prompt.
41: * @param defaultValue An optional default value.
42: * @param validators Additional validators to use.
43: * @return {@code this}
44: */
45: @SuppressWarnings("unchecked")
46: InputProvider needString(String id, String prompt, Optional<String> defaultValue,
47: Validator<String>... validators) throws InputProviderException;
48:
49: /**
50: * Adds a predefined string value. Requires that {@link #needString(String, String, Optional, Optional)} is called
51: * for the same field before requesting data from the user, otherwise calling this operation has no effect.
52: *
53: * @param id The ID of the field.
54: * @param fixedValue The corresponding value.
55: * @return {@code this}
56: */
57: InputProvider fixedString(String id, String fixedValue) throws InputProviderException;
58:
59: /**
60: * Indicates the need for an integer value from the user.
61: *
62: * @param id The ID of the field.
63: * @param prompt The prompt.
64: * @param defaultValue An optional default value.
65: * @param validators Additional validators to use.
66: * @return {@code this}
67: */
68: @SuppressWarnings("unchecked")
69: InputProvider needInteger(String id, String prompt, Optional<Integer> defaultValue,
70: Validator<Integer>... validators) throws InputProviderException;
71:
72: /**
73: * Adds a predefined integer value. Requires that {@link #needInteger(String, String, Optional, Optional, Optional)}
74: * is called for the same field before requesting data from the user, otherwise calling this operation has no
75: * effect.
76: *
77: * @param id The ID of the field.
78: * @param fixedValue The corresponding value.
79: * @return {@code this}
80: */
81: InputProvider fixedInteger(String id, Integer fixedValue) throws InputProviderException;
82:
83: /**
84: * Indicates the need for a boolean value from the user.
85: *
86: * @param id The ID of the field.
87: * @param prompt The prompt.
88: * @param defaultValue An optional default value.
89: * @param validators Additional validators to use.
90: * @return {@code this}
91: */
92: @SuppressWarnings("unchecked")
93: InputProvider needBoolean(String id, String prompt, Optional<Boolean> defaultValue,
94: Validator<Boolean>... validators) throws InputProviderException;
95:
96: /**
97: * Adds a predefined boolean value. Requires that {@link #needBoolean(String, String, Optional)} is called for the
98: * same field before requesting data from the user, otherwise calling this operation has no effect.
99: *
100: * @param id The ID of the field.
101: * @param fixedValue The corresponding value.
102: * @return {@code this}
103: */
104: InputProvider fixedBoolean(String id, Boolean fixedValue) throws InputProviderException;
105:
106: /**
107: * Indicates the need for one of multiple objects from the user.
108: *
109: * @param id The ID of the field.
110: * @param prompt The prompt.
111: * @param defaultValue An optional default value.
112: * @param objectSet The values to choose from. May be arbitrary objects; the mapping is established through their
113: * string values retrieved by calling {@link Object#toString()}
114: * @return {@code this}
115: */
116: InputProvider needObject(String id, String prompt, Optional<Object> defaultValue, Set<? extends Object> objectSet)
117: throws InputProviderException;
118:
119: /**
120: * Adds a predefined object reference. Requires that {@link #needObject(String, String, Optional, List)} is called
121: * for the same field before requesting data from the user, otherwise calling this operation has no effect.
122: *
123: * @param id The ID of the field.
124: * @param fixedValue The corresponding value.
125: * @return {@code this}
126: */
127: InputProvider fixedObject(String id, Object fixedValue) throws InputProviderException;
128:
129: /**
130: * Requests the data from the user.
131: *
132: * @param title Some title for the user interface.
133: * @return The data mapping field IDs to their contents.
134: * @throws InputProviderException if the operation has been aborted prematurely (e.g. if the user cancelled a
135: * dialog).
136: */
137: Map<String, Object> requestData(String title) throws InputProviderException;
138:
139: /**
140: * Creates a new instance of this input provider for requesting the next set of data from the user.
141: *
142: * @param lastDataSet The data requested the last time. May be empty.
143: */
144: InputProvider getNext(Map<String, Object> lastDataSet);
145: }