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}