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