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 }