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 * IMPORTANT: Looking up a topic this way requires the corresponding type to be indexed with indexing mode
049 * <code>dm4.core.key</code>.
050 */
051 Topic getTopic(String key, SimpleValue value, boolean fetchComposite);
052
053 /**
054 * Looks up topics by key and value. String values can contain wildcards like "*".
055 * <p>
056 * IMPORTANT: Looking up topics this way requires the corresponding type to be indexed with indexing mode
057 * <code>dm4.core.key</code>.
058 */
059 List<Topic> getTopics(String key, SimpleValue value, boolean fetchComposite);
060
061 ResultList<RelatedTopic> getTopics(String topicTypeUri, boolean fetchComposite, int maxResultSize);
062
063 /**
064 * Performs a fulltext search.
065 * <p>
066 * IMPORTANT: Searching topics this way requires the corresponding type to be indexed with indexing mode
067 * <code>dm4.core.fulltext</code> or <code>dm4.core.fulltext_key</code>.
068 *
069 * @param fieldUri The URI of the data field to search. If null is provided all fields are searched. ### FIXDOC
070 */
071 List<Topic> searchTopics(String searchTerm, String fieldUri);
072
073 Iterable<Topic> getAllTopics();
074
075 // ---
076
077 Topic createTopic(TopicModel model, ClientState clientState);
078
079 Directives updateTopic(TopicModel model, ClientState clientState);
080
081 Directives deleteTopic(long topicId);
082
083
084
085 // === Associations ===
086
087 Association getAssociation(long assocId, boolean fetchComposite);
088
089 /**
090 * Returns the association between two topics, qualified by association type and both role types.
091 * If no such association exists <code>null</code> is returned.
092 * If more than one association exist, a runtime exception is thrown.
093 *
094 * @param assocTypeUri Association type filter. Pass <code>null</code> to switch filter off.
095 */
096 Association getAssociation(String assocTypeUri, long topic1Id, long topic2Id,
097 String roleTypeUri1, String roleTypeUri2,
098 boolean fetchComposite);
099
100 Association getAssociationBetweenTopicAndAssociation(String assocTypeUri, long topicId, long assocId,
101 String topicRoleTypeUri, String assocRoleTypeUri,
102 boolean fetchComposite);
103
104 // ---
105
106 List<RelatedAssociation> getAssociations(String assocTypeUri);
107
108 /**
109 * Returns all associations between two topics. If no such association exists an empty set is returned.
110 */
111 List<Association> getAssociations(long topic1Id, long topic2Id);
112
113 /**
114 * Returns the associations between two topics. If no such association exists an empty set is returned.
115 *
116 * @param assocTypeUri Association type filter. Pass <code>null</code> to switch filter off.
117 */
118 List<Association> getAssociations(long topic1Id, long topic2Id, String assocTypeUri);
119
120 // ---
121
122 Iterable<Association> getAllAssociations();
123
124 // ---
125
126 Association createAssociation(AssociationModel model, ClientState clientState);
127
128 Directives updateAssociation(AssociationModel model, ClientState clientState);
129
130 Directives deleteAssociation(long assocId);
131
132
133
134 // === Topic Types ===
135
136 List<String> getTopicTypeUris();
137
138 TopicType getTopicType(String topicTypeUri);
139
140 List<TopicType> getAllTopicTypes();
141
142 // ---
143
144 TopicType createTopicType(TopicTypeModel model, ClientState clientState);
145
146 Directives updateTopicType(TopicTypeModel model, ClientState clientState);
147
148 Directives deleteTopicType(String topicTypeUri);
149
150
151
152 // === Association Types ===
153
154 List<String> getAssociationTypeUris();
155
156 AssociationType getAssociationType(String assocTypeUri);
157
158 List<AssociationType> getAllAssociationTypes();
159
160 // ---
161
162 AssociationType createAssociationType(AssociationTypeModel model, ClientState clientState);
163
164 Directives updateAssociationType(AssociationTypeModel model, ClientState clientState);
165
166 Directives deleteAssociationType(String assocTypeUri);
167
168
169
170 // === Plugins ===
171
172 Plugin getPlugin(String pluginUri);
173
174 List<PluginInfo> getPluginInfo();
175
176
177
178 // === Events ===
179
180 void fireEvent(DeepaMehtaEvent event, Object... params);
181
182 void deliverEvent(String pluginUri, DeepaMehtaEvent event, Object... params);
183
184
185
186 // === Properties ===
187
188 List<Topic> getTopicsByProperty(String propUri, Object propValue);
189
190 List<Topic> getTopicsByPropertyRange(String propUri, Number from, Number to);
191
192 List<Association> getAssociationsByProperty(String propUri, Object propValue);
193
194 List<Association> getAssociationsByPropertyRange(String propUri, Number from, Number to);
195
196
197
198 // === Misc ===
199
200 DeepaMehtaTransaction beginTx();
201
202 TypeStorage getTypeStorage();
203 }