View Javadoc
1   package de.fhdw.wtf.persistence.facade;
2   
3   import java.math.BigInteger;
4   import java.util.Collection;
5   import java.util.Date;
6   
7   import de.fhdw.wtf.persistence.exception.PersistenceException;
8   import de.fhdw.wtf.persistence.meta.Association;
9   import de.fhdw.wtf.persistence.meta.Link;
10  import de.fhdw.wtf.persistence.meta.MapAssociation;
11  import de.fhdw.wtf.persistence.meta.MapLink;
12  import de.fhdw.wtf.persistence.meta.Object;
13  import de.fhdw.wtf.persistence.meta.Transaction;
14  import de.fhdw.wtf.persistence.meta.UnidirectionalAssociation;
15  import de.fhdw.wtf.persistence.meta.UnidirectionalLink;
16  import de.fhdw.wtf.persistence.meta.UserObject;
17  import de.fhdw.wtf.persistence.meta.UserType;
18  import de.fhdw.wtf.persistence.utils.Tuple;
19  
20  /**
21   * An Interface to represent a facade towards the database to manipulate the Instance Layer of the database.
22   * 
23   */
24  public interface ObjectFacade {
25  	
26  	/**
27  	 * Wildcard character in use for Kleene closure
28  	 */
29  	char REGEX_CHAR_KLEENE_STAR = '%';
30  	
31  	// ---------- Date:Find ----------
32  	
33  	/**
34  	 * Provides a Collection of {@link de.fhdw.wtf.persistence.meta.UserObject User Objects} which are owners of the
35  	 * {@link de.fhdw.wtf.persistence.meta.Association Association} {@code association}, which points to a String value
36  	 * which is like {@code string} and the link between the user Object and the String has been published before
37  	 * {@code date} and if the link has been deleted, the deletion date must be before {@code date}. SQL wildcards in
38  	 * {@code string} are allowed.
39  	 * 
40  	 * @param association
41  	 *            An UnidirectionalAssociation, which target is a String
42  	 * @param string
43  	 *            A given String value
44  	 * @param date
45  	 *            The moment in time the object graph is queried.
46  	 * @return A Set of User Objects.
47  	 * @throws PersistenceException
48  	 *             This exception occurs if there are any problems contacting the database.
49  	 */
50  	Collection<UserObject> find(Association association, String string, Date date) throws PersistenceException;
51  	
52  	/**
53  	 * Provides a Collection of User Objects which are owners of the Association association, which points to a Integer
54  	 * value which is like s and the link between the user Object and the String has been published before d and if the
55  	 * link has been deleted, the deletion date must be before d.
56  	 * 
57  	 * @param association
58  	 *            An UnidirectionalAssociation, which target is an Integer
59  	 * @param integer
60  	 *            A given Integer value
61  	 * @param date
62  	 *            The moment in time the object graph is queried.
63  	 * @return A Set of User Objects.
64  	 * @throws PersistenceException
65  	 *             This exception occurs if there are any problems contacting the database.
66  	 */
67  	Collection<UserObject> find(Association association, BigInteger integer, Date date) throws PersistenceException;
68  	
69  	// ---------- Date:Get ----------
70  	
71  	/**
72  	 * Provides a collection of Tuples of Links and Objects. The Links are instances of association and their owner is
73  	 * owner. The Objects are the targets of each link. The published date of the link are before date and possible
74  	 * deletion dates of the links are after date. So date specifies the moment of time the object graph is queried.
75  	 * 
76  	 * @param owner
77  	 *            An User Object.
78  	 * @param association
79  	 *            An association where the owner points to type(o)
80  	 * @param date
81  	 *            A moment in time the object graph is queried.
82  	 * @return A Set of Tuples, where the first component is a link and the second component is an Object.
83  	 * @throws PersistenceException
84  	 *             This exception occurs if there are any problems contacting the database.
85  	 */
86  	Collection<Tuple<UnidirectionalLink, Object>> get(UserObject owner, UnidirectionalAssociation association, Date date)
87  			throws PersistenceException;
88  	
89  	// ---------- Date:Get:Map ----------
90  	
91  	/**
92  	 * Provides a collection of Objects for a map. The Links are instances of association and their owner is owner. The
93  	 * Objects are the targets of each link. The published date of the link are before date and possible deletion dates
94  	 * of the links are after date. So date specifies the moment of time the object graph is queried.
95  	 * 
96  	 * @param owner
97  	 *            An User Object.
98  	 * @param association
99  	 *            An association where the owner points to type(o)
100 	 * @param key
101 	 *            The map-key
102 	 * @param date
103 	 *            A moment in time the object graph is queried.
104 	 * @return A Set of Tuples, where the first component is a link and the second component is an Object.
105 	 * @throws PersistenceException
106 	 *             This exception occurs if there are any problems contacting the database.
107 	 */
108 	Collection<Object> get(UserObject owner, MapAssociation association, String key, Date date)
109 			throws PersistenceException;
110 	
111 	/**
112 	 * Provides a collection of Objects for a map. The Links are instances of association and their owner is owner. The
113 	 * Objects are the targets of each link. The published date of the link are before date and possible deletion dates
114 	 * of the links are after date. So date specifies the moment of time the object graph is queried.
115 	 * 
116 	 * @param owner
117 	 *            An User Object.
118 	 * @param association
119 	 *            An association where the owner points to type(o)
120 	 * @param key
121 	 *            The map-key
122 	 * @param date
123 	 *            A moment in time the object graph is queried.
124 	 * @return A Set of Tuples, where the first component is a link and the second component is an Object.
125 	 * @throws PersistenceException
126 	 *             This exception occurs if there are any problems contacting the database.
127 	 */
128 	Collection<Object> get(UserObject owner, MapAssociation association, BigInteger key, Date date)
129 			throws PersistenceException;
130 	
131 	/**
132 	 * Provides a collection of Objects for a map. The Links are instances of association and their owner is owner. The
133 	 * Objects are the targets of each link. The published date of the link are before date and possible deletion dates
134 	 * of the links are after date. So date specifies the moment of time the object graph is queried.
135 	 * 
136 	 * @param owner
137 	 *            An User Object.
138 	 * @param association
139 	 *            An association where the owner points to type(o)
140 	 * @param key
141 	 *            The map-key
142 	 * @param date
143 	 *            A moment in time the object graph is queried.
144 	 * @return A Set of Tuples, where the first component is a link and the second component is an Object.
145 	 * @throws PersistenceException
146 	 *             This exception occurs if there are any problems contacting the database.
147 	 */
148 	Collection<Object> get(UserObject owner, MapAssociation association, UserObject key, Date date)
149 			throws PersistenceException;
150 	
151 	// ---------- Date:InverseGet ----------
152 	
153 	/**
154 	 * Provides a collection of Tuples of Links and UserObjects. The Links are instances of a and their owner is o. The
155 	 * Objects are the targets of each link. The published date of the link are before d and possible deletion dates of
156 	 * the links are after d. So d specifies the moment of time the object graph is queried.
157 	 * 
158 	 * @param s
159 	 *            A String.
160 	 * @param association
161 	 *            An association where the owner points to type(o)
162 	 * @param date
163 	 *            A moment in time the object graph is queried.
164 	 * @return A Set of Tuples, where the first component is a UnidirectionalLink and the second component is an user
165 	 *         object.
166 	 * @throws PersistenceException
167 	 *             This exception occurs if there are any problems contacting the database.
168 	 */
169 	// Collection<Tuple<UnidirectionalLink, UserObject>>
170 	// inverseGet(String s, UnidirectionalAssociation association, Date date)
171 	// throws PersistenceException;
172 	
173 	/**
174 	 * Provides a collection of Tuples of Links and Objects. The Links are instances of a and their owner is o. The
175 	 * Objects are the targets of each link. The published date of the link are before d and possible deletion dates of
176 	 * the links are after d. So d specifies the moment of time the object graph is queried.
177 	 * 
178 	 * @param i
179 	 *            An Interger.
180 	 * @param association
181 	 *            An association where the owner points to type(o)
182 	 * @param date
183 	 *            A moment in time the object graph is queried.
184 	 * @return A Set of Tuples, where the first component is a UnidirectionalLink and the second component is an user
185 	 *         object.
186 	 * @throws PersistenceException
187 	 *             This exception occurs if there are any problems contacting the database.
188 	 */
189 	// Collection<Tuple<UnidirectionalLink, UserObject>>
190 	// inverseGet(Integer i, UnidirectionalAssociation association, Date date)
191 	// throws PersistenceException;
192 	
193 	/**
194 	 * Provides a collection of Tuples of Links and Objects. The Links are instances of association and their target is
195 	 * target. The Objects are the targets of each link. The published date of the link are before date and possible
196 	 * deletion dates of the links are after date. So date specifies the moment of time the object graph is queried.
197 	 * 
198 	 * @param target
199 	 *            An User Object.
200 	 * @param association
201 	 *            An association where the owner points to type(o)
202 	 * @param date
203 	 *            A moment in time the object graph is queried.
204 	 * @return A Set of Tuples, where the first component is a UnidirectionalLink and the second component is an user
205 	 *         object.
206 	 * @throws PersistenceException
207 	 *             This exception occurs if there are any problems contacting the database.
208 	 */
209 	Collection<Tuple<UnidirectionalLink, UserObject>> inverseGet(UserObject target,
210 			UnidirectionalAssociation association,
211 			Date date) throws PersistenceException;
212 	
213 	// ---------- Date:InverseGet:Map ----------
214 	
215 	/**
216 	 * Provides a owner for a map association. The UserObjects are the owner of each link. The published date of the
217 	 * link are before date and possible deletion dates of the links are after date. So date specifies the moment of
218 	 * time the object graph is queried.
219 	 * 
220 	 * @param target
221 	 *            An User Object represents the target.
222 	 * @param association
223 	 *            An association where the owner points to type(o)
224 	 * @param date
225 	 *            A moment in time the object graph is queried.
226 	 * @return A Set of Tuples, where the first component is the owner and the second is the key.
227 	 * @throws PersistenceException
228 	 *             This exception occurs if there are any problems contacting the database.
229 	 */
230 	Collection<Tuple<UserObject, Object>> inverseGet(UserObject target, MapAssociation association, Date date)
231 			throws PersistenceException;
232 	
233 	/**
234 	 * Provides a owner for a map association. The UserObjects are the owner of each link. The published date of the
235 	 * link are before date and possible deletion dates of the links are after date. So date specifies the moment of
236 	 * time the object graph is queried.
237 	 * 
238 	 * @param target
239 	 *            An User Object represents the target.
240 	 * @param association
241 	 *            An association where the owner points to type(o)
242 	 * @param date
243 	 *            A moment in time the object graph is queried.
244 	 * @return A Set of Tuples, where the first component is the owner and the second is the key.
245 	 * @throws PersistenceException
246 	 *             This exception occurs if there are any problems contacting the database.
247 	 */
248 	Collection<Tuple<UserObject, Object>> inverseGet(String target, MapAssociation association, Date date)
249 			throws PersistenceException;
250 	
251 	//
252 	/**
253 	 * Provides a owner for a map association. The UserObjects are the owner of each link. The published date of the
254 	 * link are before date and possible deletion dates of the links are after date. So date specifies the moment of
255 	 * time the object graph is queried.
256 	 * 
257 	 * @param target
258 	 *            An User Object represents the target.
259 	 * @param association
260 	 *            An association where the owner points to type(o)
261 	 * @param date
262 	 *            A moment in time the object graph is queried.
263 	 * @return A Set of Tuples, where the first component is the owner and the second is the key.
264 	 * @throws PersistenceException
265 	 *             This exception occurs if there are any problems contacting the database.
266 	 */
267 	Collection<Tuple<UserObject, Object>> inverseGet(BigInteger target, MapAssociation association, Date date)
268 			throws PersistenceException;
269 	
270 	// ---------- Trans:Find ----------
271 	
272 	/**
273 	 * Provides a Set of User Objects which have an association to a String Value, which value is like string and which
274 	 * are in the scope of the transaction transaction. User Objects which are in the scope of transaction are created
275 	 * by transaction or currently published and not not yet deleted by transaction.
276 	 * 
277 	 * @param association
278 	 *            An UnidirectionalAssociation towards a String, where the owner is a supertype to the type of the User
279 	 *            Objects.
280 	 * @param string
281 	 *            A given String value. SQL Wildcards are allowed.
282 	 * @param transaction
283 	 *            A currently open Transaction.
284 	 * @return A Set of User Objects.
285 	 * @throws PersistenceException
286 	 *             This exception occurs if there are any problems contacting the database.
287 	 */
288 	Collection<UserObject> find(Association association, String string, Transaction transaction)
289 			throws PersistenceException;
290 	
291 	/**
292 	 * Provides a Set of User Objects which have an association to an Integer Value, which value is like integer and
293 	 * which are in the scope of the transaction. User Objects which are in the scope of transaction are created by
294 	 * transaction or currently published and not not yet deleted by transaction.
295 	 * 
296 	 * @param association
297 	 *            An UnidirectionalAssociation towards an Integer, where the owner is a supertype to the type of the
298 	 *            User Objects.
299 	 * @param integer
300 	 *            A given Integer Value.
301 	 * @param transaction
302 	 *            A currently open Transaction.
303 	 * @return A Set of User Objects.
304 	 * @throws PersistenceException
305 	 *             This exception occurs if there are any problems contacting the database.
306 	 */
307 	Collection<UserObject> find(Association association, BigInteger integer, Transaction transaction)
308 			throws PersistenceException;
309 	
310 	// ---------- Trans:Get ----------
311 	
312 	/**
313 	 * Provides a collection of Tuples of Links and Objects. The Links are instances of the UnidirectionalAssociation
314 	 * association. And the Objects are the owner of the Links. type(owner) has to be is subtype of the owner of the
315 	 * UnidirectionalAssociation association. The Links and Objects are in the scope of the Transaction transaction.
316 	 * This means, that they are either created by transaction or currently published and not yet deleted.
317 	 * 
318 	 * @param owner
319 	 *            A User Objects, which type has an association a.
320 	 * @param association
321 	 *            An UnidirectionalAssociation with type(o) = owner
322 	 * @param transaction
323 	 *            A currently open Transaction.
324 	 * @return A Set of Tuples, where the first component is a link and the second component is an Object.
325 	 * @throws PersistenceException
326 	 *             This exception occurs if there are any problems contacting the database.
327 	 */
328 	Collection<Tuple<UnidirectionalLink, Object>> get(UserObject owner,
329 			UnidirectionalAssociation association,
330 			Transaction transaction) throws PersistenceException;
331 	
332 	// ---------- Trans:Get:Map ----------
333 	
334 	/**
335 	 * Provides the target from a map link. The Links are instances of the MapAssociation association. And the Objects
336 	 * are the owner of the Links. type(owner) has to be is subtype of the owner of the MapAssociation association. The
337 	 * Links and Objects are in the scope of the Transaction transaction. This means, that they are either created by
338 	 * transaction or currently published and not yet deleted.
339 	 * 
340 	 * @param owner
341 	 *            A User Objects, which type has an association a.
342 	 * @param association
343 	 *            An UnidirectionalAssociation with type(o) = owner
344 	 * @param key
345 	 *            The map-key
346 	 * @param transaction
347 	 *            A currently open Transaction.
348 	 * @return A Set of Tuples, where the first component is a link and the second component is an Object.
349 	 * @throws PersistenceException
350 	 *             This exception occurs if there are any problems contacting the database.
351 	 */
352 	Collection<Tuple<MapLink, Object>> get(UserObject owner,
353 			MapAssociation association,
354 			String key,
355 			Transaction transaction) throws PersistenceException;
356 	
357 	/**
358 	 * Provides the target from a map link. The Links are instances of the MapAssociation association. And the Objects
359 	 * are the owner of the Links. type(owner) has to be is subtype of the owner of the MapAssociation association. The
360 	 * Links and Objects are in the scope of the Transaction transaction. This means, that they are either created by
361 	 * transaction or currently published and not yet deleted.
362 	 * 
363 	 * @param owner
364 	 *            A User Objects, which type has an association a.
365 	 * @param association
366 	 *            An UnidirectionalAssociation with type(o) = owner
367 	 * @param key
368 	 *            The map-key
369 	 * @param transaction
370 	 *            A currently open Transaction.
371 	 * @return A Set of Tuples, where the first component is a link and the second component is an Object.
372 	 * @throws PersistenceException
373 	 *             This exception occurs if there are any problems contacting the database.
374 	 */
375 	Collection<Tuple<MapLink, Object>> get(UserObject owner,
376 			MapAssociation association,
377 			BigInteger key,
378 			Transaction transaction) throws PersistenceException;
379 	
380 	/**
381 	 * Provides the target from a map link. The Links are instances of the MapAssociation association. And the Objects
382 	 * are the owner of the Links. type(owner) has to be is subtype of the owner of the MapAssociation association. The
383 	 * Links and Objects are in the scope of the Transaction transaction. This means, that they are either created by
384 	 * transaction or currently published and not yet deleted.
385 	 * 
386 	 * @param owner
387 	 *            A User Objects, which type has an association a.
388 	 * @param association
389 	 *            An UnidirectionalAssociation with type(o) = owner
390 	 * @param key
391 	 *            The map-key
392 	 * @param transaction
393 	 *            A currently open Transaction.
394 	 * @return A Set of Tuples, where the first component is a link and the second component is an Object.
395 	 * @throws PersistenceException
396 	 *             This exception occurs if there are any problems contacting the database.
397 	 */
398 	Collection<Tuple<MapLink, Object>> get(UserObject owner,
399 			MapAssociation association,
400 			UserObject key,
401 			Transaction transaction) throws PersistenceException;
402 	
403 	// ---------- Trans:InverseGet ----------
404 	
405 	/**
406 	 * Provides a collection of Tuples of Links and User Objects. The Links are instances of the
407 	 * UnidirectionalAssociation association. And the User Objects are the targets of the Links. type(target) has to be
408 	 * is subtype of the target of the UnidirectionalAssociation association. The Links and Objects are in the scope of
409 	 * the Transaction transaction. This means, that they are either created by transaction or currently published and
410 	 * not yet deleted.
411 	 * 
412 	 * @param target
413 	 *            A User Object, which type is target of an association a
414 	 * @param association
415 	 *            An UnidirectionalAssociation with type(o) = target
416 	 * @param transaction
417 	 *            A currently open Transaction.
418 	 * @return A Set of Tuples, where the first component is a UnidirectionalLink and the second component is an user
419 	 *         object.
420 	 * @throws PersistenceException
421 	 *             This exception occurs if there are any problems contacting the database.
422 	 */
423 	Collection<Tuple<UnidirectionalLink, UserObject>> inverseGet(UserObject target,
424 			UnidirectionalAssociation association,
425 			Transaction transaction) throws PersistenceException;
426 	
427 	/**
428 	 * Provides a collection of Tuples of Links and User Objects. The Links are instances of the
429 	 * UnidirectionalAssociation a. And the User Objects are the owners of the Links. type(o) has to be is subtype of
430 	 * the target of the UnidirectionalAssociation a. The Links and Objects are in the scope of the Transaction t. This
431 	 * means, that they are either created by t or currently published and not yet deleted.
432 	 * 
433 	 * @param o
434 	 *            A User Object, which type is target of an association a
435 	 * @param association
436 	 *            An UnidirectionalAssociation with type(o) = target
437 	 * @param transaction
438 	 *            A currently open Transaction.
439 	 * @return A Set of Tuples, where the first component is a UnidirectionalLink and the second component is an user
440 	 *         object.
441 	 * @throws PersistenceException
442 	 *             This exception occurs if there are any problems contacting the database.
443 	 */
444 	// Collection<Tuple<UnidirectionalLink, UserObject>>
445 	// inverseGet(String s, UnidirectionalAssociation association, Transaction
446 	// transaction) throws PersistenceException;
447 	
448 	/**
449 	 * Provides a collection of Tuples of Links and User Objects. The Links are instances of the
450 	 * UnidirectionalAssociation a. And the User Objects are the owners of the Links. type(o) has to be is subtype of
451 	 * the target of the UnidirectionalAssociation a. The Links and Objects are in the scope of the Transaction t. This
452 	 * means, that they are either created by t or currently published and not yet deleted.
453 	 * 
454 	 * @param o
455 	 *            A User Object, which type is target of an association a
456 	 * @param association
457 	 *            An UnidirectionalAssociation with type(o) = target
458 	 * @param transaction
459 	 *            A currently open Transaction.
460 	 * @return A Set of Tuples, where the first component is a UnidirectionalLink and the second component is an user
461 	 *         object.
462 	 * @throws PersistenceException
463 	 *             This exception occurs if there are any problems contacting the database.
464 	 */
465 	// Collection<Tuple<UnidirectionalLink, UserObject>>
466 	// inverseGet(Integer i, UnidirectionalAssociation association, Transaction
467 	// transaction) throws PersistenceException;
468 	
469 	// ---------- Trans:InverseGet:Map ----------
470 	
471 	/**
472 	 * Provides a collection of Tuples of the Owner and Key for a map association. The User Objects are the owners.
473 	 * type(target) has to be is subtype of the target of the MapAssociation association. The Keys and Owner are in the
474 	 * scope of the Transaction transaction. This means, that they are either created by transaction or currently
475 	 * published and not yet deleted.
476 	 * 
477 	 * @param target
478 	 *            A User Object, which type is target of an association a
479 	 * @param association
480 	 *            An UnidirectionalAssociation with type(o) = target
481 	 * @param transaction
482 	 *            A currently open Transaction.
483 	 * @return A Set of Tuples, where the first component is a UnidirectionalLink and the second component is an user
484 	 *         object.
485 	 * @throws PersistenceException
486 	 *             This exception occurs if there are any problems contacting the database.
487 	 */
488 	Collection<Tuple<UserObject, Object>> inverseGet(UserObject target,
489 			MapAssociation association,
490 			Transaction transaction) throws PersistenceException;
491 	
492 	/**
493 	 * Provides a collection of Tuples of the Owner and Key for a map association. The User Objects are the owners.
494 	 * type(target) has to be is subtype of the target of the MapAssociation association. The Keys and Owner are in the
495 	 * scope of the Transaction transaction. This means, that they are either created by transaction or currently
496 	 * published and not yet deleted.
497 	 * 
498 	 * @param target
499 	 *            A User Object, which type is target of an association a
500 	 * @param association
501 	 *            An UnidirectionalAssociation with type(o) = target
502 	 * @param transaction
503 	 *            A currently open Transaction.
504 	 * @return A Set of Tuples, where the first component is a UnidirectionalLink and the second component is an user
505 	 *         object.
506 	 * @throws PersistenceException
507 	 *             This exception occurs if there are any problems contacting the database.
508 	 */
509 	Collection<Tuple<UserObject, Object>> inverseGet(String target, MapAssociation association, Transaction transaction)
510 			throws PersistenceException;
511 	
512 	/**
513 	 * Provides a collection of Tuples of the Owner and Key for a map association. The User Objects are the owners.
514 	 * type(target) has to be is subtype of the target of the MapAssociation association. The Keys and Owner are in the
515 	 * scope of the Transaction transaction. This means, that they are either created by transaction or currently
516 	 * published and not yet deleted.
517 	 * 
518 	 * @param target
519 	 *            A User Object, which type is target of an association a
520 	 * @param association
521 	 *            An UnidirectionalAssociation with type(o) = target
522 	 * @param transaction
523 	 *            A currently open Transaction.
524 	 * @return A Set of Tuples, where the first component is a UnidirectionalLink and the second component is an user
525 	 *         object.
526 	 * @throws PersistenceException
527 	 *             This exception occurs if there are any problems contacting the database.
528 	 */
529 	Collection<Tuple<UserObject, Object>> inverseGet(BigInteger target,
530 			MapAssociation association,
531 			Transaction transaction) throws PersistenceException;
532 	
533 	// ---------- Other ----------
534 	
535 	/**
536 	 * Provides true if before and after are in conflict, e.g. accessing Objects and Links in a modifying manner, when
537 	 * before is committed before after.
538 	 * 
539 	 * @param before
540 	 *            A currently open transaction.
541 	 * @param after
542 	 *            A currently open transaction.
543 	 * @return Provides true if the two transactions are in conflict, when before commits before after.
544 	 * @throws PersistenceException
545 	 *             This exception occurs if there are any problems contacting the database.
546 	 */
547 	boolean isInConflict(Transaction before, Transaction after) throws PersistenceException;
548 	
549 	/**
550 	 * Checks if a given Transaction is a transaction which is not yet committed or rolled back if t is an adhoc
551 	 * transaction.
552 	 * 
553 	 * @param transaction
554 	 *            A possible open Transaction.
555 	 * @return Provides true if t is an open transaction.
556 	 * @throws PersistenceException
557 	 *             This exception occurs if there are any problems contacting the database.
558 	 */
559 	boolean isOpenTransaction(Transaction transaction) throws PersistenceException;
560 	
561 	/**
562 	 * This Method creates an instance of a given User Type. The User Type has to be a concrete Type, otherwise an
563 	 * exception will be thrown. If the the type is also a user transaction, a new transaction will be opened.
564 	 * 
565 	 * @param type
566 	 *            A User Type which is not abstract.
567 	 * @param transaction
568 	 *            A Transaction in which scope the instance will be created.
569 	 * @return Provides the new Instance to type.
570 	 * @throws PersistenceException
571 	 *             This exception occurs if there are any problems contacting the database.
572 	 */
573 	UserObject create(UserType type, Transaction transaction) throws PersistenceException;
574 	
575 	/**
576 	 * This Method deletes a given User Object in the scope of transaction transaction. This method only works if there
577 	 * are Links anymore, where object is owner or target of the link (defensive manner).
578 	 * 
579 	 * @param object
580 	 *            A User Objects, which is accessible in the scope of transaction and there are links anymore pointing
581 	 *            to.
582 	 * @param transaction
583 	 *            A currently open transaction.
584 	 * @throws PersistenceException
585 	 *             This exception occurs if there are any problems contacting the database.
586 	 */
587 	void delete(UserObject object, Transaction transaction) throws PersistenceException;
588 	
589 	// ---------- Set ----------
590 	
591 	/**
592 	 * This method creates a link between the user Object owner and the user object target. If the association is
593 	 * essential a modified flag from transaction will be set for owner. Also if the association is unique, the previos
594 	 * existing link will be deleted. The UnidirectionalLink will be an instance of the UnidirectionalAssociation
595 	 * association. The owner has to be a subtype of association.owner and the target has to be a subtype of
596 	 * association.target otherwise an exception will be thrown. Also owner and target have to be in scope of
597 	 * transaction. The link also will be created in scope of transaction.
598 	 * 
599 	 * @param owner
600 	 *            A User Object, where type <= a.owner
601 	 * @param association
602 	 *            An UnidirectionalAssociation
603 	 * @param target
604 	 *            A User Object, where type <= a.target
605 	 * @param transaction
606 	 *            A currently open Transaction.
607 	 * @return Provides a new UnidirectionalLink, which is an instance of a.
608 	 * @throws PersistenceException
609 	 *             This exception occurs if there are any problems contacting the database or there are consistencies
610 	 *             violated.
611 	 */
612 	UnidirectionalLink set(UserObject owner,
613 			UnidirectionalAssociation association,
614 			UserObject target,
615 			Transaction transaction) throws PersistenceException;
616 	
617 	/**
618 	 * This method creates a link between the user Object owner and the user object target. If the association is
619 	 * essential a modified flag from transaction will be set for owner. Also if the association is unique, the previos
620 	 * existing link will be deleted. The UnidirectionalLink will be an instance of the UnidirectionalAssociation
621 	 * association. The owner has to be a subtype of association.owner and the target has to be a subtype of
622 	 * association.target otherwise an exception will be thrown. Also owner and target have to be in scope of
623 	 * transaction. The link also will be created in scope of transaction.
624 	 * 
625 	 * @param owner
626 	 *            A User Object, where type <= a.owner
627 	 * @param association
628 	 *            An UnidirectionalAssociation
629 	 * @param target
630 	 *            An Integer Value
631 	 * @param transaction
632 	 *            A currently open Transaction.
633 	 * @return Provides a new UnidirectionalLink, which is an instance of a.
634 	 * @throws PersistenceException
635 	 *             This exception occurs if there are any problems contacting the database or there consistencies are
636 	 *             violated.
637 	 */
638 	UnidirectionalLink set(UserObject owner,
639 			UnidirectionalAssociation association,
640 			BigInteger target,
641 			Transaction transaction) throws PersistenceException;
642 	
643 	/**
644 	 * This method creates a link between the user Object owner and the user object target. If the association is
645 	 * essential a modified flag from transaction will be set for owner. Also if the association is unique, the previos
646 	 * existing link will be deleted. The UnidirectionalLink will be an instance of the UnidirectionalAssociation
647 	 * association. The owner has to be a subtype of association.owner and the target has to be a subtype of
648 	 * association.target otherwise an exception will be thrown. Also owner and target have to be in scope of
649 	 * transaction. The link also will be created in scope of transaction.
650 	 * 
651 	 * @param owner
652 	 *            A User Object, where type <= a.owner
653 	 * @param association
654 	 *            An UnidirectionalAssociation
655 	 * @param target
656 	 *            An String Value.
657 	 * @param transaction
658 	 *            A currently open Transaction.
659 	 * @return Provides a new UnidirectionalLink, which is an instance of a.
660 	 * @throws PersistenceException
661 	 *             This exception occurs if there are any problems contacting the database or there are consistencies
662 	 *             violated.
663 	 */
664 	UnidirectionalLink set(UserObject owner,
665 			UnidirectionalAssociation association,
666 			String target,
667 			Transaction transaction) throws PersistenceException;
668 	
669 	// ---------- Put ----------
670 	
671 	/**
672 	 * This method creates a link between the user Object owner, the user object target and the map key. If the
673 	 * association is essential a modified flag from t will be set for owner. The previos existing link will be deleted.
674 	 * The MapLink will be an instance of the MapAssociation association. The owner has to be a subtype of
675 	 * association.owner, the target has to be a subtype of association.target and the key has to be a subtype of
676 	 * association.keyType otherwise an exception will be thrown. Also owner, target and key have to be in scope of
677 	 * transaction. The link also will be created in scope of transaction.
678 	 * 
679 	 * @param owner
680 	 *            A User Object, where type <= a.owner
681 	 * @param association
682 	 *            An MapAssociation
683 	 * @param target
684 	 *            A User Object, where type <= a.target
685 	 * @param key
686 	 *            The key-Object
687 	 * @param transaction
688 	 *            A currently open Transaction.
689 	 * @return Provides a new MapLink, which is an instance of association.
690 	 * @throws PersistenceException
691 	 *             This exception occurs if there are any problems contacting the database or there are consistencies
692 	 *             violated.
693 	 */
694 	MapLink put(UserObject owner, MapAssociation association, UserObject target, String key, Transaction transaction)
695 			throws PersistenceException;
696 	
697 	/**
698 	 * This method creates a link between the user Object owner, the user object target and the map key. If the
699 	 * association is essential a modified flag from t will be set for owner. The previos existing link will be deleted.
700 	 * The MapLink will be an instance of the MapAssociation association. The owner has to be a subtype of
701 	 * association.owner, the target has to be a subtype of association.target and the key has to be a subtype of
702 	 * association.keyType otherwise an exception will be thrown. Also owner, target and key have to be in scope of
703 	 * transaction. The link also will be created in scope of transaction.
704 	 * 
705 	 * @param owner
706 	 *            A User Object, where type <= a.owner
707 	 * @param association
708 	 *            An MapAssociation
709 	 * @param target
710 	 *            An Integer Value
711 	 * @param key
712 	 *            The key-Object
713 	 * @param transaction
714 	 *            A currently open Transaction.
715 	 * @return Provides a new MapLink, which is an instance of association.
716 	 * @throws PersistenceException
717 	 *             This exception occurs if there are any problems contacting the database or there consistencies are
718 	 *             violated.
719 	 */
720 	MapLink put(UserObject owner, MapAssociation association, BigInteger target, String key, Transaction transaction)
721 			throws PersistenceException;
722 	
723 	/**
724 	 * This method creates a link between the user Object owner, the user object target and the map key. If the
725 	 * association is essential a modified flag from t will be set for owner. The previos existing link will be deleted.
726 	 * The MapLink will be an instance of the MapAssociation association. The owner has to be a subtype of
727 	 * association.owner, the target has to be a subtype of association.target and the key has to be a subtype of
728 	 * association.keyType otherwise an exception will be thrown. Also owner, target and key have to be in scope of
729 	 * transaction. The link also will be created in scope of transaction.
730 	 * 
731 	 * @param owner
732 	 *            A User Object, where type <= a.owner
733 	 * @param association
734 	 *            An MapAssociation
735 	 * @param target
736 	 *            An String Value.
737 	 * @param key
738 	 *            The key-Object
739 	 * @param transaction
740 	 *            A currently open Transaction.
741 	 * @return Provides a new MapLink, which is an instance of association.
742 	 * @throws PersistenceException
743 	 *             This exception occurs if there are any problems contacting the database or there are consistencies
744 	 *             violated.
745 	 */
746 	MapLink put(UserObject owner, MapAssociation association, String target, String key, Transaction transaction)
747 			throws PersistenceException;
748 	
749 	/**
750 	 * This method creates a link between the user Object owner, the user object target and the map key. If the
751 	 * association is essential a modified flag from t will be set for owner. The previos existing link will be deleted.
752 	 * The MapLink will be an instance of the MapAssociation association. The owner has to be a subtype of
753 	 * association.owner, the target has to be a subtype of association.target and the key has to be a subtype of
754 	 * association.keyType otherwise an exception will be thrown. Also owner, target and key have to be in scope of
755 	 * transaction. The link also will be created in scope of transaction.
756 	 * 
757 	 * @param owner
758 	 *            A User Object, where type <= a.owner
759 	 * @param association
760 	 *            An MapAssociation
761 	 * @param target
762 	 *            A User Object, where type <= a.target
763 	 * @param key
764 	 *            The key-Object
765 	 * @param transaction
766 	 *            A currently open Transaction.
767 	 * @return Provides a new MapLink, which is an instance of association.
768 	 * @throws PersistenceException
769 	 *             This exception occurs if there are any problems contacting the database or there are consistencies
770 	 *             violated.
771 	 */
772 	MapLink put(UserObject owner, MapAssociation association, UserObject target, BigInteger key, Transaction transaction)
773 			throws PersistenceException;
774 	
775 	/**
776 	 * This method creates a link between the user Object owner, the user object target and the map key. If the
777 	 * association is essential a modified flag from t will be set for owner. The previos existing link will be deleted.
778 	 * The MapLink will be an instance of the MapAssociation association. The owner has to be a subtype of
779 	 * association.owner, the target has to be a subtype of association.target and the key has to be a subtype of
780 	 * association.keyType otherwise an exception will be thrown. Also owner, target and key have to be in scope of
781 	 * transaction. The link also will be created in scope of transaction.
782 	 * 
783 	 * @param owner
784 	 *            A User Object, where type <= a.owner
785 	 * @param association
786 	 *            An MapAssociation
787 	 * @param target
788 	 *            An Integer Value
789 	 * @param key
790 	 *            The key-Object
791 	 * @param transaction
792 	 *            A currently open Transaction.
793 	 * @return Provides a new MapLink, which is an instance of association.
794 	 * @throws PersistenceException
795 	 *             This exception occurs if there are any problems contacting the database or there consistencies are
796 	 *             violated.
797 	 */
798 	MapLink put(UserObject owner, MapAssociation association, BigInteger target, BigInteger key, Transaction transaction)
799 			throws PersistenceException;
800 	
801 	/**
802 	 * This method creates a link between the user Object owner, the user object target and the map key. If the
803 	 * association is essential a modified flag from t will be set for owner. The previos existing link will be deleted.
804 	 * The MapLink will be an instance of the MapAssociation association. The owner has to be a subtype of
805 	 * association.owner, the target has to be a subtype of association.target and the key has to be a subtype of
806 	 * association.keyType otherwise an exception will be thrown. Also owner, target and key have to be in scope of
807 	 * transaction. The link also will be created in scope of transaction.
808 	 * 
809 	 * @param owner
810 	 *            A User Object, where type <= a.owner
811 	 * @param association
812 	 *            An MapAssociation
813 	 * @param target
814 	 *            An String Value.
815 	 * @param key
816 	 *            The key-Object
817 	 * @param transaction
818 	 *            A currently open Transaction.
819 	 * @return Provides a new MapLink, which is an instance of association.
820 	 * @throws PersistenceException
821 	 *             This exception occurs if there are any problems contacting the database or there are consistencies
822 	 *             violated.
823 	 */
824 	MapLink put(UserObject owner, MapAssociation association, String target, BigInteger key, Transaction transaction)
825 			throws PersistenceException;
826 	
827 	/**
828 	 * This method creates a link between the user Object owner, the user object target and the map key. If the
829 	 * association is essential a modified flag from t will be set for owner. The previos existing link will be deleted.
830 	 * The MapLink will be an instance of the MapAssociation association. The owner has to be a subtype of
831 	 * association.owner, the target has to be a subtype of association.target and the key has to be a subtype of
832 	 * association.keyType otherwise an exception will be thrown. Also owner, target and key have to be in scope of
833 	 * transaction. The link also will be created in scope of transaction.
834 	 * 
835 	 * @param owner
836 	 *            A User Object, where type <= a.owner
837 	 * @param association
838 	 *            An MapAssociation
839 	 * @param target
840 	 *            A User Object, where type <= a.target
841 	 * @param key
842 	 *            The key-Object
843 	 * @param transaction
844 	 *            A currently open Transaction.
845 	 * @return Provides a new MapLink, which is an instance of association.
846 	 * @throws PersistenceException
847 	 *             This exception occurs if there are any problems contacting the database or there are consistencies
848 	 *             violated.
849 	 */
850 	MapLink put(UserObject owner, MapAssociation association, UserObject target, UserObject key, Transaction transaction)
851 			throws PersistenceException;
852 	
853 	/**
854 	 * This method creates a link between the user Object owner, the user object target and the map key. If the
855 	 * association is essential a modified flag from t will be set for owner. The previos existing link will be deleted.
856 	 * The MapLink will be an instance of the MapAssociation association. The owner has to be a subtype of
857 	 * association.owner, the target has to be a subtype of association.target and the key has to be a subtype of
858 	 * association.keyType otherwise an exception will be thrown. Also owner, target and key have to be in scope of
859 	 * transaction. The link also will be created in scope of transaction.
860 	 * 
861 	 * @param owner
862 	 *            A User Object, where type <= a.owner
863 	 * @param association
864 	 *            An MapAssociation
865 	 * @param target
866 	 *            An Integer Value
867 	 * @param key
868 	 *            The key-Object
869 	 * @param transaction
870 	 *            A currently open Transaction.
871 	 * @return Provides a new MapLink, which is an instance of association.
872 	 * @throws PersistenceException
873 	 *             This exception occurs if there are any problems contacting the database or there consistencies are
874 	 *             violated.
875 	 */
876 	MapLink put(UserObject owner, MapAssociation association, BigInteger target, UserObject key, Transaction transaction)
877 			throws PersistenceException;
878 	
879 	/**
880 	 * This method creates a link between the user Object owner, the user object target and the map key. If the
881 	 * association is essential a modified flag from t will be set for owner. The previos existing link will be deleted.
882 	 * The MapLink will be an instance of the MapAssociation association. The owner has to be a subtype of
883 	 * association.owner, the target has to be a subtype of association.target and the key has to be a subtype of
884 	 * association.keyType otherwise an exception will be thrown. Also owner, target and key have to be in scope of
885 	 * transaction. The link also will be created in scope of transaction.
886 	 * 
887 	 * @param owner
888 	 *            A User Object, where type <= a.owner
889 	 * @param association
890 	 *            An MapAssociation
891 	 * @param target
892 	 *            An String Value.
893 	 * @param key
894 	 *            The key-Object
895 	 * @param transaction
896 	 *            A currently open Transaction.
897 	 * @return Provides a new MapLink, which is an instance of association.
898 	 * @throws PersistenceException
899 	 *             This exception occurs if there are any problems contacting the database or there are consistencies
900 	 *             violated.
901 	 */
902 	MapLink put(UserObject owner, MapAssociation association, String target, UserObject key, Transaction transaction)
903 			throws PersistenceException;
904 	
905 	// ---------- Other ----------
906 	
907 	/**
908 	 * This method deletes a given Link in the scope of the transaction transaction. If the type of the link has an
909 	 * essential flag an modified flag for the owner of the Link will be set.
910 	 * 
911 	 * @param link
912 	 *            A UnidirectionalLink which will be deleted.
913 	 * @param transaction
914 	 *            A currently open transaction.
915 	 * @throws PersistenceException
916 	 *             This exception occurs if there are any problems contacting the database.
917 	 */
918 	void unset(Link link, Transaction transaction) throws PersistenceException;
919 	
920 	/**
921 	 * This Methods commits a currently open transaction, so all modification transaction has done will be accessible to
922 	 * all other transaction and can be seen in future revisions. If there are other open Transactions transaction',
923 	 * where isInConflict(transaction',transaction) = true, then each transaction' will be rolled back.
924 	 * 
925 	 * @param transaction
926 	 *            A currently open transaction.
927 	 * @throws PersistenceException
928 	 *             This exception occurs if there are any problems contacting the database.
929 	 */
930 	void commit(Transaction transaction) throws PersistenceException;
931 	
932 	/**
933 	 * This methods rolls a transaction back, this means that all modifications of transaction will be removed. If
934 	 * transaction is an adhoc Transaction transaction will also be closed.
935 	 * 
936 	 * @param transaction
937 	 *            A currently open Transaction.
938 	 * @throws PersistenceException
939 	 *             This exception occurs if there are any problems contacting the database.
940 	 */
941 	void rollback(Transaction transaction) throws PersistenceException;
942 	
943 	/**
944 	 * This Methods creates a save point inside a transaction. So modifications of transaction until now are saved so it
945 	 * is possible to rollback to this save point later.
946 	 * 
947 	 * @param transaction
948 	 *            A currently open transaction.
949 	 * @throws PersistenceException
950 	 *             This exception occurs if there are any problems contacting the database.
951 	 */
952 	void savePoint(Transaction transaction) throws PersistenceException;
953 	
954 	/**
955 	 * This Method deletes all modifications of transaction since the last created save point of transaction. If
956 	 * transaction has never created a save point all modifications will be lost.
957 	 * 
958 	 * @param transaction
959 	 *            A currently open transaction.
960 	 * @throws PersistenceException
961 	 *             This exception occurs if there are any problems contacting the database.
962 	 */
963 	void rollbackToSavePoint(Transaction transaction) throws PersistenceException;
964 	
965 	/**
966 	 * This Method provides an Integer Value with the given Id. If there is no Integer value with the given id, an
967 	 * exception will be thrown.
968 	 * 
969 	 * @param id
970 	 *            An id of an integer value inside the database.
971 	 * @return Provides a Big Integer Value Object.
972 	 * @throws PersistenceException
973 	 *             This exception occurs if there are any problems contacting the database or there is not Integer Value
974 	 *             with the given id.
975 	 */
976 	BigInteger getIntForId(long id) throws PersistenceException;
977 	
978 	/**
979 	 * This Method provides a String Value with the given Id. If there is no String value with the given id, an
980 	 * exception will be thrown.
981 	 * 
982 	 * @param id
983 	 *            An id of a string value inside the database.
984 	 * @return Provides a String Value Object.
985 	 * @throws PersistenceException
986 	 *             This exception occurs if there are any problems contacting the database or there is no String with
987 	 *             the given id.
988 	 */
989 	String getStringForId(long id) throws PersistenceException;
990 	
991 	/**
992 	 * Provides the id of a given String value string. If there is no String value same as string is present inside the
993 	 * database a new String Value will be created in the database.
994 	 * 
995 	 * @param string
996 	 *            A String s
997 	 * @return The Id of s in the database.
998 	 * @throws PersistenceException
999 	 *             This exception occurs if there are any problems contacting the database.
1000 	 */
1001 	long getIdForString(String string) throws PersistenceException;
1002 	
1003 	/**
1004 	 * Provides the id of a given Integer value integer. If there is no Integer value same as is is present inside the
1005 	 * database a new Integer value will be created in the database.
1006 	 * 
1007 	 * @param integer
1008 	 *            An Integer i
1009 	 * @return The Id of i in the database.
1010 	 * @throws PersistenceException
1011 	 *             This exception occurs if there are any problems contacting the database.
1012 	 */
1013 	long getIdForInteger(BigInteger integer) throws PersistenceException;
1014 	
1015 	/**
1016 	 * This Method provides a new Adhoc Transaction, which can be used to manipulate data.
1017 	 * 
1018 	 * @return A new open Adoc Transaction.
1019 	 * @throws PersistenceException
1020 	 *             This exception occurs if there are any problems contacting the database.
1021 	 */
1022 	Transaction provideAdhocTransaction() throws PersistenceException;
1023 	
1024 	/**
1025 	 * Provides an instance of the TypeManager, an object which has knowledge about every type and association in the
1026 	 * knowledge-tier. Before you cann call this operation, you have to initialize this facade.
1027 	 * 
1028 	 * @return An Instance of the Type Manager.
1029 	 */
1030 	TypeManager getTypeManager();
1031 	
1032 	/**
1033 	 * !! ATTENTION !!! This method clears the object world completely, therefore all data will be lost. So use this
1034 	 * method carefully and only during development time !!!
1035 	 * 
1036 	 * @throws PersistenceException
1037 	 *             This exception occurs if there are any problems contacting the database.
1038 	 */
1039 	void clear() throws PersistenceException;
1040 	
1041 	/**
1042 	 * This method provides all instances for a given User Type, which can be seen in the current transaction. Because
1043 	 * the provided dataset may be large, this method created no read-flags on the returned objects, so it is possible
1044 	 * the run into race-conditions on the returned objects.
1045 	 * 
1046 	 * @param type
1047 	 *            The Type, which the reurned objects are instances of.
1048 	 * @param transaction
1049 	 *            The current Transaction, which is used
1050 	 * @return A Collection of User Types, which can be seen at the moment and are instances of the given user type.
1051 	 * @throws PersistenceException
1052 	 *             This exception occurs if there are any problems contacting the database.
1053 	 */
1054 	Collection<UserObject> findAllObjects(UserType type, Transaction transaction) throws PersistenceException;
1055 	
1056 	/**
1057 	 * This provides the UserObject with the given id and marks the corresponding Object as read, so it will be under
1058 	 * transaction control.
1059 	 * 
1060 	 * @param id
1061 	 *            The Id of the Provided User Object.
1062 	 * @param transaction
1063 	 *            The Transaction which will place the read marker on the object.
1064 	 * @return Provides a User Object with the given Id.
1065 	 * @throws PersistenceException
1066 	 *             An Exception will be thrown if something went wrong.
1067 	 */
1068 	UserObject checkUserObjectOut(long id, Transaction transaction) throws PersistenceException;
1069 	
1070 }