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 }