Package: InputProvider

InputProvider

Coverage

1: /*
2: * Copyright © 2020-2023 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.Map;
22: import java.util.Optional;
23: import java.util.Set;
24:
25: import de.fhdw.gaming.core.ui.type.validator.Validator;
26:
27: /**
28: * Provides user input by creating a dialogue with the user. First, a sequence of fields is described, then the contents
29: * of these fields are requested from the user. The form of presentation is decided by the concrete implementation. For
30: * example, this may be done by prompting the fields one after another on the text console, or by showing a GUI dialog
31: * where the user may type the data in arbitrary order and submit all data at once.
32: */
33: public interface InputProvider {
34:
35: /**
36: * Indicates the need for a string value from the user.
37: *
38: * @param id The ID of the field.
39: * @param prompt The prompt.
40: * @param defaultValue An optional default value.
41: * @param validators Additional validators to use.
42: * @return {@code this}
43: */
44: @SuppressWarnings("unchecked")
45: InputProvider needString(String id, String prompt, Optional<String> defaultValue,
46: Validator<String>... validators) throws InputProviderException;
47:
48: /**
49: * Adds a predefined string value. Requires that {@link #needString(String, String, Optional, Validator...)} is
50: * called for the same field before requesting data from the user, otherwise calling this operation has no effect.
51: *
52: * @param id The ID of the field.
53: * @param fixedValue The corresponding value.
54: * @return {@code this}
55: */
56: InputProvider fixedString(String id, String fixedValue) throws InputProviderException;
57:
58: /**
59: * Indicates the need for an integer value from the user.
60: *
61: * @param id The ID of the field.
62: * @param prompt The prompt.
63: * @param defaultValue An optional default value.
64: * @param validators Additional validators to use.
65: * @return {@code this}
66: */
67: @SuppressWarnings("unchecked")
68: InputProvider needInteger(String id, String prompt, Optional<Integer> defaultValue,
69: Validator<Integer>... validators) throws InputProviderException;
70:
71: /**
72: * Adds a predefined integer value. Requires that {@link #needInteger(String, String, Optional, Validator...)}
73: * is called for the same field before requesting data from the user, otherwise calling this operation has no
74: * effect.
75: *
76: * @param id The ID of the field.
77: * @param fixedValue The corresponding value.
78: * @return {@code this}
79: */
80: InputProvider fixedInteger(String id, Integer fixedValue) throws InputProviderException;
81:
82: /**
83: * Indicates the need for a boolean value from the user.
84: *
85: * @param id The ID of the field.
86: * @param prompt The prompt.
87: * @param defaultValue An optional default value.
88: * @param validators Additional validators to use.
89: * @return {@code this}
90: */
91: @SuppressWarnings("unchecked")
92: InputProvider needBoolean(String id, String prompt, Optional<Boolean> defaultValue,
93: Validator<Boolean>... validators) throws InputProviderException;
94:
95: /**
96: * Adds a predefined boolean value. Requires that {@link #needBoolean(String, String, Optional, Validator...)}
97: * is called for the same field before requesting data from the user, otherwise calling this operation has no
98: * 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<?> objectSet)
117: throws InputProviderException;
118:
119: /**
120: * Adds a predefined object reference. Requires that {@link #needObject(String, String, Optional, Set)} 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: * @throws InputProviderException if some input is not compatible.
144: */
145: InputProvider getNext(Map<String, Object> lastDataSet) throws InputProviderException;
146: }