001 package de.deepamehta.core.service; 002 003 import de.deepamehta.core.Association; 004 import de.deepamehta.core.AssociationType; 005 import de.deepamehta.core.DeepaMehtaObject; 006 import de.deepamehta.core.RelatedAssociation; 007 import de.deepamehta.core.RelatedTopic; 008 import de.deepamehta.core.Topic; 009 import de.deepamehta.core.TopicType; 010 import de.deepamehta.core.model.AssociationModel; 011 import de.deepamehta.core.model.AssociationTypeModel; 012 import de.deepamehta.core.model.SimpleValue; 013 import de.deepamehta.core.model.TopicModel; 014 import de.deepamehta.core.model.TopicTypeModel; 015 import de.deepamehta.core.service.ResultList; 016 import de.deepamehta.core.service.accesscontrol.AccessControl; 017 import de.deepamehta.core.storage.spi.DeepaMehtaTransaction; 018 019 import 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 */ 037 public 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,boolean)} 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 * Returns the association between two topics, qualified by association type and both role types. 099 * If no such association exists <code>null</code> is returned. 100 * If more than one association exist, a runtime exception is thrown. 101 * 102 * @param assocTypeUri Association type filter. Pass <code>null</code> to switch filter off. 103 */ 104 Association getAssociation(String assocTypeUri, long topic1Id, long topic2Id, 105 String roleTypeUri1, String roleTypeUri2); 106 107 Association getAssociationBetweenTopicAndAssociation(String assocTypeUri, long topicId, long assocId, 108 String topicRoleTypeUri, String assocRoleTypeUri); 109 110 // --- 111 112 ResultList<RelatedAssociation> getAssociations(String assocTypeUri); 113 114 /** 115 * Returns all associations between two topics. If no such association exists an empty set is returned. 116 */ 117 List<Association> getAssociations(long topic1Id, long topic2Id); 118 119 /** 120 * Returns the associations between two topics. If no such association exists an empty set is returned. 121 * 122 * @param assocTypeUri Association type filter. Pass <code>null</code> to switch filter off. 123 */ 124 List<Association> getAssociations(long topic1Id, long topic2Id, String assocTypeUri); 125 126 // --- 127 128 Iterable<Association> getAllAssociations(); 129 130 long[] getPlayerIds(long assocId); 131 132 // --- 133 134 Association createAssociation(AssociationModel model); 135 136 void updateAssociation(AssociationModel model); 137 138 void deleteAssociation(long assocId); 139 140 141 142 // === Topic Types === 143 144 List<String> getTopicTypeUris(); 145 146 TopicType getTopicType(String topicTypeUri); 147 148 List<TopicType> getAllTopicTypes(); 149 150 // --- 151 152 TopicType createTopicType(TopicTypeModel model); 153 154 void updateTopicType(TopicTypeModel model); 155 156 void deleteTopicType(String topicTypeUri); 157 158 159 160 // === Association Types === 161 162 List<String> getAssociationTypeUris(); 163 164 AssociationType getAssociationType(String assocTypeUri); 165 166 List<AssociationType> getAllAssociationTypes(); 167 168 // --- 169 170 AssociationType createAssociationType(AssociationTypeModel model); 171 172 void updateAssociationType(AssociationTypeModel model); 173 174 void deleteAssociationType(String assocTypeUri); 175 176 177 178 // === Role Types === 179 180 Topic createRoleType(TopicModel model); 181 182 183 184 // === Generic Object === 185 186 DeepaMehtaObject getObject(long id); 187 188 189 190 // === Plugins === 191 192 Plugin getPlugin(String pluginUri); 193 194 List<PluginInfo> getPluginInfo(); 195 196 197 198 // === Events === 199 200 void fireEvent(DeepaMehtaEvent event, Object... params); 201 202 void deliverEvent(String pluginUri, DeepaMehtaEvent event, Object... params); 203 204 205 206 // === Properties === 207 208 /** 209 * Returns a topic's or association's property value associated with the given property URI. 210 * If there's no property value associated with the property URI an exception is thrown. 211 * 212 * @param id a topic ID, or an association ID 213 */ 214 Object getProperty(long id, String propUri); 215 216 /** 217 * Checks whether for a given topic or association a property value is associated with a given property URI. 218 * 219 * @param id a topic ID, or an association ID 220 */ 221 boolean hasProperty(long id, String propUri); 222 223 // Note: there is no setter here. If we want one we actually need 2 setters: one for topics, one for assocs. 224 // This is because the storage layer maintains separate indexes for topics and assocs. 225 226 // --- 227 228 List<Topic> getTopicsByProperty(String propUri, Object propValue); 229 230 List<Topic> getTopicsByPropertyRange(String propUri, Number from, Number to); 231 232 List<Association> getAssociationsByProperty(String propUri, Object propValue); 233 234 List<Association> getAssociationsByPropertyRange(String propUri, Number from, Number to); 235 236 237 238 // === Misc === 239 240 DeepaMehtaTransaction beginTx(); 241 242 TypeStorage getTypeStorage(); // ### TODO: drop this 243 AccessControl getAccessControl(); // ### TODO: drop this 244 245 Object getDatabaseVendorObject(); 246 }