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    // ### TODO: rename "put" methods to "set" to be consistent with ChildTopics interface.
166
167    /**
168     * Puts a value in a single-valued child.
169     * An existing value is overwritten.
170     */
171    ChildTopicsModel put(String assocDefUri, RelatedTopicModel value);
172
173    ChildTopicsModel put(String assocDefUri, TopicModel value);
174
175    // ---
176
177    /**
178     * Convenience method to put a *simple* value in a single-valued child.
179     * An existing value is overwritten.
180     *
181     * @param   value   a String, Integer, Long, Double, or a Boolean.
182     *
183     * @return  this ChildTopicsModel.
184     */
185    ChildTopicsModel put(String assocDefUri, Object value);
186
187    /**
188     * Convenience method to put a *composite* value in a single-valued child.
189     * An existing value is overwritten.
190     *
191     * @return  this ChildTopicsModel.
192     */
193    ChildTopicsModel put(String assocDefUri, ChildTopicsModel value);
194
195    // ---
196
197    /**
198     * Puts a by-ID topic reference in a single-valued child.
199     * An existing reference is overwritten.
200     */
201    ChildTopicsModel putRef(String assocDefUri, long refTopicId);
202
203    /**
204     * Puts a by-URI topic reference in a single-valued child.
205     * An existing reference is overwritten.
206     */
207    ChildTopicsModel putRef(String assocDefUri, String refTopicUri);
208
209    // ---
210
211    /**
212     * Puts a by-ID topic deletion reference to a single-valued child.
213     * An existing value is overwritten.
214     */
215    ChildTopicsModel putDeletionRef(String assocDefUri, long refTopicId);
216
217    /**
218     * Puts a by-URI topic deletion reference to a single-valued child.
219     * An existing value is overwritten.
220     */
221    ChildTopicsModel putDeletionRef(String assocDefUri, String refTopicUri);
222
223    // ---
224
225    /**
226     * Removes a single-valued child.
227     */
228    ChildTopicsModel remove(String assocDefUri);
229
230    // --- Multiple-valued Childs ---
231
232    /**
233     * Adds a value to a multiple-valued child.
234     */
235    ChildTopicsModel add(String assocDefUri, RelatedTopicModel value);
236
237    ChildTopicsModel add(String assocDefUri, TopicModel value);
238
239    /**
240     * Sets the values of a multiple-valued child.
241     * Existing values are overwritten.
242     */
243    ChildTopicsModel put(String assocDefUri, List<RelatedTopicModel> values);
244
245    /**
246     * Removes a value from a multiple-valued child.
247     */
248    ChildTopicsModel remove(String assocDefUri, TopicModel value);
249
250    // ---
251
252    /**
253     * Adds a by-ID topic reference to a multiple-valued child.
254     */
255    ChildTopicsModel addRef(String assocDefUri, long refTopicId);
256
257    /**
258     * Adds a by-URI topic reference to a multiple-valued child.
259     */
260    ChildTopicsModel addRef(String assocDefUri, String refTopicUri);
261
262    // ---
263
264    /**
265     * Adds a by-ID topic deletion reference to a multiple-valued child.
266     */
267    ChildTopicsModel addDeletionRef(String assocDefUri, long refTopicId);
268
269    /**
270     * Adds a by-URI topic deletion reference to a multiple-valued child.
271     */
272    ChildTopicsModel addDeletionRef(String assocDefUri, String refTopicUri);
273
274
275
276    // ===
277
278    ChildTopicsModel clone();
279}