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