001package de.deepamehta.core.model;
002
003import de.deepamehta.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    /**
063     * Convenience accessor for the *simple* value of a single-valued child.
064     * Throws if the child doesn't exist.
065     */
066    String getString(String assocDefUri);
067
068    /**
069     * Convenience accessor for the *simple* value of a single-valued child.
070     * Returns a default value if the child doesn't exist.
071     */
072    String getString(String assocDefUri, String defaultValue);
073
074    // ---
075
076    /**
077     * Convenience accessor for the *simple* value of a single-valued child.
078     * Throws if the child doesn't exist.
079     */
080    int getInt(String assocDefUri);
081
082    /**
083     * Convenience accessor for the *simple* value of a single-valued child.
084     * Returns a default value if the child doesn't exist.
085     */
086    int getInt(String assocDefUri, int defaultValue);
087
088    // ---
089
090    /**
091     * Convenience accessor for the *simple* value of a single-valued child.
092     * Throws if the child doesn't exist.
093     */
094    long getLong(String assocDefUri);
095
096    /**
097     * Convenience accessor for the *simple* value of a single-valued child.
098     * Returns a default value if the child doesn't exist.
099     */
100    long getLong(String assocDefUri, long defaultValue);
101
102    // ---
103
104    /**
105     * Convenience accessor for the *simple* value of a single-valued child.
106     * Throws if the child doesn't exist.
107     */
108    double getDouble(String assocDefUri);
109
110    /**
111     * Convenience accessor for the *simple* value of a single-valued child.
112     * Returns a default value if the child doesn't exist.
113     */
114    double getDouble(String assocDefUri, double defaultValue);
115
116    // ---
117
118    /**
119     * Convenience accessor for the *simple* value of a single-valued child.
120     * Throws if the child doesn't exist.
121     */
122    boolean getBoolean(String assocDefUri);
123
124    /**
125     * Convenience accessor for the *simple* value of a single-valued child.
126     * Returns a default value if the child doesn't exist.
127     */
128    boolean getBoolean(String assocDefUri, boolean defaultValue);
129
130    // ---
131
132    /**
133     * Convenience accessor for the *simple* value of a single-valued child.
134     * Throws if the child doesn't exist.
135     */
136    Object getObject(String assocDefUri);
137
138    /**
139     * Convenience accessor for the *simple* value of a single-valued child.
140     * Returns a default value if the child doesn't exist.
141     */
142    Object getObject(String assocDefUri, Object defaultValue);
143
144    // ---
145
146    /**
147     * Convenience accessor for the *composite* value of a single-valued child.
148     * Throws if the child doesn't exist.
149     */
150    ChildTopicsModel getChildTopicsModel(String assocDefUri);
151
152    /**
153     * Convenience accessor for the *composite* value of a single-valued child.
154     * Returns a default value if the child doesn't exist.
155     */
156    ChildTopicsModel getChildTopicsModel(String assocDefUri, ChildTopicsModel defaultValue);
157
158    // Note: there are no convenience accessors for a multiple-valued child.
159
160
161
162    // === Manipulators ===
163
164    // --- Single-valued Childs ---
165
166    // ### TODO: rename "put" methods to "set" to be consistent with ChildTopics interface.
167
168    /**
169     * Puts a value in a single-valued child.
170     * An existing value is overwritten.
171     */
172    ChildTopicsModel put(String assocDefUri, RelatedTopicModel value);
173
174    ChildTopicsModel put(String assocDefUri, TopicModel value);
175
176    // ---
177
178    /**
179     * Convenience method to put a *simple* value in a single-valued child.
180     * An existing value is overwritten.
181     *
182     * @param   value   a String, Integer, Long, Double, or a Boolean.
183     *
184     * @return  this ChildTopicsModel.
185     */
186    ChildTopicsModel put(String assocDefUri, Object value);
187
188    /**
189     * Convenience method to put a *composite* value in a single-valued child.
190     * An existing value is overwritten.
191     *
192     * @return  this ChildTopicsModel.
193     */
194    ChildTopicsModel put(String assocDefUri, ChildTopicsModel value);
195
196    // ---
197
198    /**
199     * Puts a by-ID topic reference in a single-valued child.
200     * An existing reference is overwritten.
201     */
202    ChildTopicsModel putRef(String assocDefUri, long refTopicId);
203
204    /**
205     * Puts a by-URI topic reference in a single-valued child.
206     * An existing reference is overwritten.
207     */
208    ChildTopicsModel putRef(String assocDefUri, String refTopicUri);
209
210    // ---
211
212    /**
213     * Puts a by-ID topic deletion reference in a single-valued child.
214     * An existing value is overwritten.
215     */
216    ChildTopicsModel putDeletionRef(String assocDefUri, long refTopicId);
217
218    /**
219     * Puts a by-URI topic deletion reference in a single-valued child.
220     * An existing value is overwritten.
221     */
222    ChildTopicsModel putDeletionRef(String assocDefUri, String refTopicUri);
223
224    // ---
225
226    /**
227     * Removes a single-valued child.
228     */
229    ChildTopicsModel remove(String assocDefUri);
230
231    // --- Multiple-valued Childs ---
232
233    /**
234     * Adds a value to a multiple-valued child.
235     */
236    ChildTopicsModel add(String assocDefUri, RelatedTopicModel value);
237
238    ChildTopicsModel add(String assocDefUri, TopicModel value);
239
240    /**
241     * Sets the values of a multiple-valued child.
242     * Existing values are overwritten.
243     */
244    ChildTopicsModel put(String assocDefUri, List<RelatedTopicModel> values);
245
246    /**
247     * Removes a value from a multiple-valued child.
248     */
249    ChildTopicsModel remove(String assocDefUri, TopicModel value);
250
251    // ---
252
253    /**
254     * Adds a by-ID topic reference to a multiple-valued child.
255     */
256    ChildTopicsModel addRef(String assocDefUri, long refTopicId);
257
258    /**
259     * Adds a by-URI topic reference to a multiple-valued child.
260     */
261    ChildTopicsModel addRef(String assocDefUri, String refTopicUri);
262
263    // ---
264
265    /**
266     * Adds a by-ID topic deletion reference to a multiple-valued child.
267     */
268    ChildTopicsModel addDeletionRef(String assocDefUri, long refTopicId);
269
270    /**
271     * Adds a by-URI topic deletion reference to a multiple-valued child.
272     */
273    ChildTopicsModel addDeletionRef(String assocDefUri, String refTopicUri);
274
275
276
277    // ===
278
279    ChildTopicsModel clone();
280}