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}