001package systems.dmx.core.model;
002
003import systems.dmx.core.JSONEnabled;
004
005import java.util.List;
006
007
008
009/**
010 * A recursive composite of key/value pairs. ### FIXDOC
011 * <p>
012 * Keys are strings, values are non-null atomic (string, int, long, double, boolean)
013 * or again a <code>ChildTopicsModel</code>. ### FIXDOC
014 */
015public interface ChildTopicsModel extends JSONEnabled, Iterable<String> {
016
017
018
019    // === Accessors ===
020
021    /**
022     * Accesses a single-valued child.
023     * Throws if there is no such child.
024     */
025    RelatedTopicModel getTopic(String assocDefUri);
026
027    /**
028     * Accesses a single-valued child.
029     * Returns <code>null</code> if there is no such child.
030     */
031    RelatedTopicModel getTopicOrNull(String assocDefUri);
032
033    // ---
034
035    /**
036     * Accesses a multiple-valued child.
037     * Throws if there is no such child. ### TODO: return empty list instead
038     */
039    List<? extends RelatedTopicModel> getTopics(String assocDefUri);
040
041    /**
042     * Accesses a multiple-valued child.
043     * Returns <code>null</code> if there is no such child.
044     * ### TODO: drop this method
045     */
046    List<? extends RelatedTopicModel> getTopicsOrNull(String assocDefUri);
047
048    // ---
049
050    /**
051     * Accesses a child generically, regardless of single-valued or multiple-valued.
052     * Returns null if there is no such child.
053     *
054     * @return  A RelatedTopicModel or List<RelatedTopicModel>, or null if there is no such child.
055     */
056    Object get(String assocDefUri);
057
058
059
060    // === Convenience Accessors ===
061
062    // ### TODO: transform defaultValue methods into getXXOrNull() form, analogous to ChildTopics interface
063
064    /**
065     * Convenience accessor for the *simple* value of a single-valued child.
066     * Throws if the child doesn't exist.
067     */
068    String getString(String assocDefUri);
069
070    /**
071     * Convenience accessor for the *simple* value of a single-valued child.
072     * Returns a default value if the child doesn't exist.
073     */
074    String getString(String assocDefUri, String defaultValue);
075
076    // ---
077
078    /**
079     * Convenience accessor for the *simple* value of a single-valued child.
080     * Throws if the child doesn't exist.
081     */
082    int getInt(String assocDefUri);
083
084    /**
085     * Convenience accessor for the *simple* value of a single-valued child.
086     * Returns a default value if the child doesn't exist.
087     */
088    int getInt(String assocDefUri, int defaultValue);
089
090    // ---
091
092    /**
093     * Convenience accessor for the *simple* value of a single-valued child.
094     * Throws if the child doesn't exist.
095     */
096    long getLong(String assocDefUri);
097
098    /**
099     * Convenience accessor for the *simple* value of a single-valued child.
100     * Returns a default value if the child doesn't exist.
101     */
102    long getLong(String assocDefUri, long defaultValue);
103
104    // ---
105
106    /**
107     * Convenience accessor for the *simple* value of a single-valued child.
108     * Throws if the child doesn't exist.
109     */
110    double getDouble(String assocDefUri);
111
112    /**
113     * Convenience accessor for the *simple* value of a single-valued child.
114     * Returns a default value if the child doesn't exist.
115     */
116    double getDouble(String assocDefUri, double defaultValue);
117
118    // ---
119
120    /**
121     * Convenience accessor for the *simple* value of a single-valued child.
122     * Throws if the child doesn't exist.
123     */
124    boolean getBoolean(String assocDefUri);
125
126    /**
127     * Convenience accessor for the *simple* value of a single-valued child.
128     * Returns a default value if the child doesn't exist.
129     */
130    boolean getBoolean(String assocDefUri, boolean defaultValue);
131
132    // ---
133
134    /**
135     * Convenience accessor for the *simple* value of a single-valued child.
136     * Throws if the child doesn't exist.
137     */
138    Object getObject(String assocDefUri);
139
140    /**
141     * Convenience accessor for the *simple* value of a single-valued child.
142     * Returns a default value if the child doesn't exist.
143     */
144    Object getObject(String assocDefUri, Object defaultValue);
145
146    // ---
147
148    /**
149     * Convenience accessor for the *composite* value of a single-valued child.
150     * Throws if the child doesn't exist.
151     */
152    ChildTopicsModel getChildTopicsModel(String assocDefUri);
153
154    /**
155     * Convenience accessor for the *composite* value of a single-valued child.
156     * Returns a default value if the child doesn't exist.
157     */
158    ChildTopicsModel getChildTopicsModel(String assocDefUri, ChildTopicsModel defaultValue);
159
160    // Note: there are no convenience accessors for a multiple-valued child.
161
162
163
164    // === Manipulators ===
165
166    // --- Single-valued Childs ---
167
168    // ### TODO: rename "put" methods to "set" to be consistent with ChildTopics interface.
169
170    /**
171     * Puts a value in a single-valued child.
172     * An existing value is overwritten.
173     */
174    ChildTopicsModel put(String assocDefUri, RelatedTopicModel value);
175
176    ChildTopicsModel put(String assocDefUri, TopicModel value);
177
178    // ---
179
180    /**
181     * Convenience method to put a *simple* value in a single-valued child.
182     * An existing value is overwritten.
183     *
184     * @param   value   a String, Integer, Long, Double, or a Boolean.
185     *
186     * @return  this ChildTopicsModel.
187     */
188    ChildTopicsModel put(String assocDefUri, Object value);
189
190    /**
191     * Convenience method to put a *composite* value in a single-valued child.
192     * An existing value is overwritten.
193     *
194     * @return  this ChildTopicsModel.
195     */
196    ChildTopicsModel put(String assocDefUri, ChildTopicsModel value);
197
198    // ---
199
200    /**
201     * Puts a by-ID topic reference in a single-valued child.
202     * An existing reference is overwritten.
203     */
204    ChildTopicsModel putRef(String assocDefUri, long refTopicId);
205
206    /**
207     * Puts a by-URI topic reference in a single-valued child.
208     * An existing reference is overwritten.
209     */
210    ChildTopicsModel putRef(String assocDefUri, String refTopicUri);
211
212    // ---
213
214    /**
215     * Puts a by-ID topic deletion reference in a single-valued child.
216     * An existing value is overwritten.
217     */
218    ChildTopicsModel putDeletionRef(String assocDefUri, long refTopicId);
219
220    /**
221     * Puts a by-URI topic deletion reference in a single-valued child.
222     * An existing value is overwritten.
223     */
224    ChildTopicsModel putDeletionRef(String assocDefUri, String refTopicUri);
225
226    // ---
227
228    /**
229     * Removes a single-valued child.
230     */
231    ChildTopicsModel remove(String assocDefUri);
232
233    // --- Multiple-valued Childs ---
234
235    /**
236     * Adds a value to a multiple-valued child.
237     */
238    ChildTopicsModel add(String assocDefUri, RelatedTopicModel value);
239
240    ChildTopicsModel add(String assocDefUri, TopicModel value);
241
242    /**
243     * Sets the values of a multiple-valued child.
244     * Existing values are overwritten.
245     */
246    ChildTopicsModel put(String assocDefUri, List<RelatedTopicModel> values);
247
248    /**
249     * Removes a value from a multiple-valued child.
250     */
251    ChildTopicsModel remove(String assocDefUri, TopicModel value);
252
253    // ---
254
255    /**
256     * Adds a by-ID topic reference to a multiple-valued child.
257     */
258    ChildTopicsModel addRef(String assocDefUri, long refTopicId);
259
260    /**
261     * Adds a by-URI topic reference to a multiple-valued child.
262     */
263    ChildTopicsModel addRef(String assocDefUri, String refTopicUri);
264
265    // ---
266
267    /**
268     * Adds a by-ID topic deletion reference to a multiple-valued child.
269     */
270    ChildTopicsModel addDeletionRef(String assocDefUri, long refTopicId);
271
272    /**
273     * Adds a by-URI topic deletion reference to a multiple-valued child.
274     */
275    ChildTopicsModel addDeletionRef(String assocDefUri, String refTopicUri);
276
277
278
279    // ===
280
281    ChildTopicsModel clone();
282}