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 id, boolean fetchComposite);
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, boolean fetchComposite);
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, boolean fetchComposite);
065
066 ResultList<RelatedTopic> getTopics(String topicTypeUri, boolean fetchComposite, 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, ClientState clientState);
084
085 Directives updateTopic(TopicModel model, ClientState clientState);
086
087 Directives deleteTopic(long topicId);
088
089
090
091 // === Associations ===
092
093 Association getAssociation(long assocId, boolean fetchComposite);
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 boolean fetchComposite);
105
106 Association getAssociationBetweenTopicAndAssociation(String assocTypeUri, long topicId, long assocId,
107 String topicRoleTypeUri, String assocRoleTypeUri,
108 boolean fetchComposite);
109
110 // ---
111
112 List<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 // ---
131
132 Association createAssociation(AssociationModel model, ClientState clientState);
133
134 Directives updateAssociation(AssociationModel model, ClientState clientState);
135
136 Directives deleteAssociation(long assocId);
137
138
139
140 // === Topic Types ===
141
142 List<String> getTopicTypeUris();
143
144 TopicType getTopicType(String topicTypeUri);
145
146 List<TopicType> getAllTopicTypes();
147
148 // ---
149
150 TopicType createTopicType(TopicTypeModel model, ClientState clientState);
151
152 Directives updateTopicType(TopicTypeModel model, ClientState clientState);
153
154 Directives deleteTopicType(String topicTypeUri);
155
156
157
158 // === Association Types ===
159
160 List<String> getAssociationTypeUris();
161
162 AssociationType getAssociationType(String assocTypeUri);
163
164 List<AssociationType> getAllAssociationTypes();
165
166 // ---
167
168 AssociationType createAssociationType(AssociationTypeModel model, ClientState clientState);
169
170 Directives updateAssociationType(AssociationTypeModel model, ClientState clientState);
171
172 Directives deleteAssociationType(String assocTypeUri);
173
174
175
176 // === Plugins ===
177
178 Plugin getPlugin(String pluginUri);
179
180 List<PluginInfo> getPluginInfo();
181
182
183
184 // === Events ===
185
186 void fireEvent(DeepaMehtaEvent event, Object... params);
187
188 void deliverEvent(String pluginUri, DeepaMehtaEvent event, Object... params);
189
190
191
192 // === Properties ===
193
194 List<Topic> getTopicsByProperty(String propUri, Object propValue);
195
196 List<Topic> getTopicsByPropertyRange(String propUri, Number from, Number to);
197
198 List<Association> getAssociationsByProperty(String propUri, Object propValue);
199
200 List<Association> getAssociationsByPropertyRange(String propUri, Number from, Number to);
201
202
203
204 // === Misc ===
205
206 DeepaMehtaTransaction beginTx();
207
208 TypeStorage getTypeStorage();
209
210 Object getDatabaseVendorObject();
211 }