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: InputProvider needString(String id, String prompt, Optional<String> defaultValue,
46: @SuppressWarnings("unchecked") Validator<String>... validators) throws InputProviderException;
47:
48: /**
49: * Adds a predefined string value. Requires that {@link #needString(String, String, Optional, Optional)} is called
50: * 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: InputProvider needInteger(String id, String prompt, Optional<Integer> defaultValue,
68: @SuppressWarnings("unchecked") Validator<Integer>... validators) throws InputProviderException;
69:
70: /**
71: * Adds a predefined integer value. Requires that {@link #needInteger(String, String, Optional, Optional, Optional)}
72: * is called for the same field before requesting data from the user, otherwise calling this operation has no
73: * effect.
74: *
75: * @param id The ID of the field.
76: * @param fixedValue The corresponding value.
77: * @return {@code this}
78: */
79: InputProvider fixedInteger(String id, Integer fixedValue) throws InputProviderException;
80:
81: /**
82: * Indicates the need for a boolean value from the user.
83: *
84: * @param id The ID of the field.
85: * @param prompt The prompt.
86: * @param defaultValue An optional default value.
87: * @param validators Additional validators to use.
88: * @return {@code this}
89: */
90: InputProvider needBoolean(String id, String prompt, Optional<Boolean> defaultValue,
91: @SuppressWarnings("unchecked") Validator<Boolean>... validators) throws InputProviderException;
92:
93: /**
94: * Adds a predefined boolean value. Requires that {@link #needBoolean(String, String, Optional)} is called for the
95: * same field before requesting data from the user, otherwise calling this operation has no effect.
96: *
97: * @param id The ID of the field.
98: * @param fixedValue The corresponding value.
99: * @return {@code this}
100: */
101: InputProvider fixedBoolean(String id, Boolean fixedValue) throws InputProviderException;
102:
103: /**
104: * Indicates the need for one of multiple objects from the user.
105: *
106: * @param id The ID of the field.
107: * @param prompt The prompt.
108: * @param defaultValue An optional default value.
109: * @param objectSet The values to choose from. May be arbitrary objects; the mapping is established through their
110: * string values retrieved by calling {@link Object#toString()}
111: * @return {@code this}
112: */
113: InputProvider needObject(String id, String prompt, Optional<Object> defaultValue, Set<? extends Object> objectSet)
114: throws InputProviderException;
115:
116: /**
117: * Adds a predefined object reference. Requires that {@link #needObject(String, String, Optional, List)} is called
118: * for the same field before requesting data from the user, otherwise calling this operation has no effect.
119: *
120: * @param id The ID of the field.
121: * @param fixedValue The corresponding value.
122: * @return {@code this}
123: */
124: InputProvider fixedObject(String id, Object fixedValue) throws InputProviderException;
125:
126: /**
127: * Requests the data from the user.
128: *
129: * @param title Some title for the user interface.
130: * @return The data mapping field IDs to their contents.
131: * @throws InputProviderException if the operation has been aborted prematurely (e.g. if the user cancelled a
132: * dialog).
133: */
134: Map<String, Object> requestData(String title) throws InputProviderException;
135:
136: /**
137: * Creates a new instance of this input provider for requesting the next set of data from the user.
138: *
139: * @param lastDataSet The data requested the last time. May be empty.
140: */
141: InputProvider getNext(Map<String, Object> lastDataSet);
142: }