001package de.deepamehta.core.service; 002 003import de.deepamehta.core.Association; 004import de.deepamehta.core.AssociationType; 005import de.deepamehta.core.DeepaMehtaObject; 006import de.deepamehta.core.RelatedAssociation; 007import de.deepamehta.core.RelatedTopic; 008import de.deepamehta.core.Topic; 009import de.deepamehta.core.TopicType; 010import de.deepamehta.core.model.AssociationModel; 011import de.deepamehta.core.model.AssociationTypeModel; 012import de.deepamehta.core.model.SimpleValue; 013import de.deepamehta.core.model.TopicModel; 014import de.deepamehta.core.model.TopicTypeModel; 015import de.deepamehta.core.service.ResultList; 016import de.deepamehta.core.service.accesscontrol.AccessControl; 017import de.deepamehta.core.storage.spi.DeepaMehtaTransaction; 018 019import java.util.List; 020 021 022 023/** 024 * Specification of the DeepaMehta core service -- the heart of DeepaMehta. 025 * <p> 026 * The responsibility of the DeepaMehta core service is to orchestrate the control flow and allow plugins to hook in. 027 * The main duties of the DeepaMehta core service are to provide access to the storage layer and to deliver events to 028 * the installed plugins. ### FIXDOC 029 * <p> 030 * The DeepaMehta core service is a realization of the <i>Inversion of Control</i> pattern. 031 * <p> 032 * The DeepaMehta core service provides methods to deal with topics, associations, types, and plugins. 033 * <p> 034 * Plugin developer notes: Inside the {@link PluginActivator} and {@link Migration} classes an instance of the 035 * DeepaMehta core service is available through the <code>dms</code> object. 036 */ 037public interface DeepaMehtaService { 038 039 040 041 // === Topics === 042 043 Topic getTopic(long topicId); 044 045 /** 046 * Looks up a single topic by exact value. 047 * If no such topic exists <code>null</code> is returned. 048 * If more than one topic is found a runtime exception is thrown. 049 * <p> 050 * Note: wildcards like "*" in String values are treated literally. They are <i>not</i> interpreted. 051 * Compare to {@link #getTopics(String,SimpleValue)} 052 * <p> 053 * IMPORTANT: Looking up a topic this way requires the corresponding type to be indexed with indexing mode 054 * <code>dm4.core.key</code>. 055 */ 056 Topic getTopic(String key, SimpleValue value); 057 058 /** 059 * Looks up topics by key and value. 060 * <p> 061 * Wildcards like "*" in String values <i>are</i> interpreted. 062 * <p> 063 * IMPORTANT: Looking up topics this way requires the corresponding type to be indexed with indexing mode 064 * <code>dm4.core.key</code>. 065 */ 066 List<Topic> getTopics(String key, SimpleValue value); 067 068 ResultList<RelatedTopic> getTopics(String topicTypeUri, int maxResultSize); 069 070 /** 071 * Performs a fulltext search. 072 * <p> 073 * IMPORTANT: Searching topics this way requires the corresponding type to be indexed with indexing mode 074 * <code>dm4.core.fulltext</code> or <code>dm4.core.fulltext_key</code>. ### FIXDOC 075 * 076 * @param fieldUri The URI of the data field to search. If null is provided all fields are searched. ### FIXDOC 077 * ### TODO: rename parameter to "key"? 078 */ 079 List<Topic> searchTopics(String searchTerm, String fieldUri); 080 081 Iterable<Topic> getAllTopics(); 082 083 // --- 084 085 Topic createTopic(TopicModel model); 086 087 void updateTopic(TopicModel model); 088 089 void deleteTopic(long topicId); 090 091 092 093 // === Associations === 094 095 Association getAssociation(long assocId); 096 097 /** 098 * Looks up a single association by exact value. 099 * If no such association exists <code>null</code> is returned. 100 * If more than one association is found a runtime exception is thrown. 101 * <p> 102 * Note: wildcards like "*" in String values are treated literally. They are <i>not</i> interpreted. 103 * Compare to {@link #getAssociations(String,SimpleValue)} 104 * <p> 105 * IMPORTANT: Looking up an association this way requires the corresponding type to be indexed with indexing mode 106 * <code>dm4.core.key</code>. 107 */ 108 Association getAssociation(String key, SimpleValue value); 109 110 /** 111 * Looks up associations by key and value. 112 * <p> 113 * Wildcards like "*" in String values <i>are</i> interpreted. 114 * <p> 115 * IMPORTANT: Looking up associations this way requires the corresponding type to be indexed with indexing mode 116 * <code>dm4.core.key</code>. 117 */ 118 List<Association> getAssociations(String key, SimpleValue value); 119 120 /** 121 * Returns the association between two topics, qualified by association type and both role types. 122 * If no such association exists <code>null</code> is returned. 123 * If more than one association exist, a runtime exception is thrown. 124 * 125 * @param assocTypeUri Association type filter. Pass <code>null</code> to switch filter off. 126 */ 127 Association getAssociation(String assocTypeUri, long topic1Id, long topic2Id, 128 String roleTypeUri1, String roleTypeUri2); 129 130 Association getAssociationBetweenTopicAndAssociation(String assocTypeUri, long topicId, long assocId, 131 String topicRoleTypeUri, String assocRoleTypeUri); 132 133 // --- 134 135 ResultList<RelatedAssociation> getAssociations(String assocTypeUri); 136 137 /** 138 * Returns all associations between two topics. If no such association exists an empty set is returned. 139 */ 140 List<Association> getAssociations(long topic1Id, long topic2Id); 141 142 /** 143 * Returns the associations between two topics. If no such association exists an empty set is returned. 144 * 145 * @param assocTypeUri Association type filter. Pass <code>null</code> to switch filter off. 146 */ 147 List<Association> getAssociations(long topic1Id, long topic2Id, String assocTypeUri); 148 149 // --- 150 151 Iterable<Association> getAllAssociations(); 152 153 long[] getPlayerIds(long assocId); 154 155 // --- 156 157 Association createAssociation(AssociationModel model); 158 159 void updateAssociation(AssociationModel model); 160 161 void deleteAssociation(long assocId); 162 163 164 165 // === Topic Types === 166 167 List<String> getTopicTypeUris(); 168 169 TopicType getTopicType(String topicTypeUri); 170 171 List<TopicType> getAllTopicTypes(); 172 173 // --- 174 175 TopicType createTopicType(TopicTypeModel model); 176 177 void updateTopicType(TopicTypeModel model); 178 179 void deleteTopicType(String topicTypeUri); 180 181 182 183 // === Association Types === 184 185 List<String> getAssociationTypeUris(); 186 187 AssociationType getAssociationType(String assocTypeUri); 188 189 List<AssociationType> getAllAssociationTypes(); 190 191 // --- 192 193 AssociationType createAssociationType(AssociationTypeModel model); 194 195 void updateAssociationType(AssociationTypeModel model); 196 197 void deleteAssociationType(String assocTypeUri); 198 199 200 201 // === Role Types === 202 203 Topic createRoleType(TopicModel model); 204 205 206 207 // === Generic Object === 208 209 DeepaMehtaObject getObject(long id); 210 211 212 213 // === Plugins === 214 215 Plugin getPlugin(String pluginUri); 216 217 List<PluginInfo> getPluginInfo(); 218 219 220 221 // === Events === 222 223 void fireEvent(DeepaMehtaEvent event, Object... params); 224 225 void deliverEvent(String pluginUri, DeepaMehtaEvent event, Object... params); 226 227 228 229 // === Properties === 230 231 /** 232 * Returns a topic's or association's property value associated with the given property URI. 233 * If there's no property value associated with the property URI an exception is thrown. 234 * 235 * @param id a topic ID, or an association ID 236 */ 237 Object getProperty(long id, String propUri); 238 239 /** 240 * Checks whether for a given topic or association a property value is associated with a given property URI. 241 * 242 * @param id a topic ID, or an association ID 243 */ 244 boolean hasProperty(long id, String propUri); 245 246 // Note: there is no setter here. If we want one we actually need 2 setters: one for topics, one for assocs. 247 // This is because the storage layer maintains separate indexes for topics and assocs. 248 249 // --- 250 251 List<Topic> getTopicsByProperty(String propUri, Object propValue); 252 253 List<Topic> getTopicsByPropertyRange(String propUri, Number from, Number to); 254 255 List<Association> getAssociationsByProperty(String propUri, Object propValue); 256 257 List<Association> getAssociationsByPropertyRange(String propUri, Number from, Number to); 258 259 260 261 // === Misc === 262 263 DeepaMehtaTransaction beginTx(); 264 265 TypeStorage getTypeStorage(); // ### TODO: drop this 266 AccessControl getAccessControl(); // ### TODO: drop this 267 268 Object getDatabaseVendorObject(); 269}