1 /*
2 * Copyright 2015 Data Archiving and Networked Services (an institute of
3 * Koninklijke Nederlandse Akademie van Wetenschappen), King's College London,
4 * Georg-August-Universitaet Goettingen Stiftung Oeffentlichen Rechts
5 *
6 * Licensed under the EUPL, Version 1.1 or – as soon they will be approved by
7 * the European Commission - subsequent versions of the EUPL (the "Licence");
8 * You may not use this work except in compliance with the Licence.
9 * You may obtain a copy of the Licence at:
10 *
11 * https://joinup.ec.europa.eu/software/page/eupl
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the Licence is distributed on an "AS IS" basis,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the Licence for the specific language governing
17 * permissions and limitations under the Licence.
18 */
19
20 package eu.ehri.project.core;
21
22 import com.tinkerpop.blueprints.CloseableIterable;
23 import com.tinkerpop.blueprints.Vertex;
24 import com.tinkerpop.frames.FramedGraph;
25 import eu.ehri.project.exceptions.IntegrityError;
26 import eu.ehri.project.exceptions.ItemNotFound;
27 import eu.ehri.project.models.EntityClass;
28 import eu.ehri.project.models.base.Entity;
29
30 import java.util.Map;
31
32 /**
33 * An abstraction over the basic {@link FramedGraph} class
34 * that provides unified CRUD semantics for low-level
35 * graph operations.
36 */
37 public interface GraphManager {
38
39 /**
40 * Get a pointer to the underlying graph.
41 */
42 FramedGraph<?> getGraph();
43
44 /**
45 * Get the id of a given vertex.
46 *
47 * @param vertex A vertex
48 * @return The vertex's string ID
49 */
50 String getId(Vertex vertex);
51
52 /**
53 * Get the id of a given vertex.
54 *
55 * @param vertex A vertex
56 * @return The vertex's string type
57 */
58 String getType(Vertex vertex);
59
60 /**
61 * Get a vertex's properties.
62 *
63 * @return a map of property objects
64 */
65 Map<String, Object> getProperties(Vertex vertex);
66
67 /**
68 * Get the type of an arbitrary vertex.
69 *
70 * @param vertex A vertex
71 * @return The vertex's entity class
72 */
73 EntityClass getEntityClass(Vertex vertex);
74
75 /**
76 * Get the type of an arbitrary framed vertex.
77 *
78 * @param entity A framed vertex
79 * @return The entity's entity class
80 */
81 EntityClass getEntityClass(Entity entity);
82
83 /**
84 * Check if a node with the given ID exists or not.
85 *
86 * @param id A string id
87 * @return Whether or not a node with that ID exists in the graph.
88 */
89 boolean exists(String id);
90
91 /**
92 * Get a node with the given ID.
93 *
94 * @param id The vertex's string ID
95 * @return The vertex
96 */
97 Vertex getVertex(String id) throws ItemNotFound;
98
99 /**
100 * Get a node with the given ID, and frame it with the given interface
101 * class.
102 *
103 * @param id The vertex's string ID
104 * @param cls The desired frame class
105 * @return The framed vertex
106 */
107 <T> T getEntity(String id, Class<T> cls) throws ItemNotFound;
108
109 /**
110 * Get a node with the given ID and type, framing it with the given
111 * interface class.
112 *
113 * @param id The vertex's string ID
114 * @param type The entity type
115 * @param cls The desired frame class
116 * @return The framed vertex
117 */
118 <T> T getEntity(String id, EntityClass type, Class<T> cls)
119 throws ItemNotFound;
120
121 /**
122 * Get a CloseableIterable of vertices with the given entity class.
123 *
124 * @param type The entity type
125 * @return An iterable of vertices belonging to that entity class
126 */
127 CloseableIterable<Vertex> getVertices(EntityClass type);
128
129 /**
130 * Get a CloseableIterable of vertices with the given ids.
131 *
132 * @param ids An iterable of String IDs
133 * @return An iterable of vertices with the given IDs. If a vertex
134 * is not found the value at the place in the input iterable will
135 * be null.
136 */
137 CloseableIterable<Vertex> getVertices(Iterable<String> ids);
138
139 /**
140 * Get a CloseableIterable of vertices with the given type, and the given
141 * key/value property.
142 *
143 * @param key the property key
144 * @param value property value
145 * @param type the entity type
146 * @return an iterable of vertices with the given key/value properties
147 */
148 CloseableIterable<Vertex> getVertices(String key, Object value, EntityClass type);
149
150 /**
151 * Get an Iterable of vertices of the given type, frames with the given
152 * interface class.
153 *
154 * @param type The entity type
155 * @return An iterable of framed vertices with the given framed class.
156 */
157 <T> CloseableIterable<T> getEntities(EntityClass type, Class<T> cls);
158
159 /**
160 * Get a CloseableIterable of entities with the given type, and the given
161 * key/value property.
162 *
163 * @param key the property key
164 * @param value property value
165 * @param type the entity type
166 * @return an iterable of entities with the given key/value properties
167 */
168 <T> CloseableIterable<T> getEntities(String key, Object value, EntityClass type, Class<T> cls);
169
170 // CRUD functions
171
172 /**
173 * Create a vertex with the given id, type, and data.
174 *
175 * @param id The vertex's string ID
176 * @param type The entity type
177 * @param data The data map
178 * @return The new vertex
179 * @throws IntegrityError if an item with the given id already exists
180 */
181 Vertex createVertex(String id, EntityClass type,
182 Map<String, ?> data) throws IntegrityError;
183
184 /**
185 * Create a vertex with the given id, type, and data.
186 *
187 * @param id The vertex's string ID
188 * @param type The entity type
189 * @param data The data map
190 * @return The updated vertex
191 */
192 Vertex updateVertex(String id, EntityClass type,
193 Map<String, ?> data) throws ItemNotFound;
194
195 /**
196 * Set a property on a vertex.
197 *
198 * @param vertex The vertex
199 * @param key The property key
200 * @param value The property value
201 */
202 void setProperty(Vertex vertex, String key, Object value);
203
204 /**
205 * Rename an existing vertex, changing its ID.
206 *
207 * @param vertex the vertex
208 * @param oldId the old ID
209 * @param newId the new ID
210 */
211 void renameVertex(Vertex vertex, String oldId, String newId);
212
213 // CRUD functions
214
215 /**
216 * Delete a vertex with the given ID.
217 *
218 * @param id The vertex's string ID
219 */
220 void deleteVertex(String id) throws ItemNotFound;
221
222 /**
223 * Delete the given vertex.
224 *
225 * @param vertex The vertex to delete
226 */
227 void deleteVertex(Vertex vertex);
228
229 /*
230 * Run graph-specific initialization code.
231 */
232 void initialize();
233 }