Package: Lists

Lists

Coverage

1: /*
2: * JOPA
3: * Copyright (C) 2024 Czech Technical University in Prague
4: *
5: * This library is free software; you can redistribute it and/or
6: * modify it under the terms of the GNU Lesser General Public
7: * License as published by the Free Software Foundation; either
8: * version 3.0 of the License, or (at your option) any later version.
9: *
10: * This library is distributed in the hope that it will be useful,
11: * but WITHOUT ANY WARRANTY; without even the implied warranty of
12: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13: * Lesser General Public License for more details.
14: *
15: * You should have received a copy of the GNU Lesser General Public
16: * License along with this library.
17: */
18: package cz.cvut.kbss.ontodriver;
19:
20: import cz.cvut.kbss.ontodriver.descriptor.ReferencedListDescriptor;
21: import cz.cvut.kbss.ontodriver.descriptor.ReferencedListValueDescriptor;
22: import cz.cvut.kbss.ontodriver.descriptor.SimpleListDescriptor;
23: import cz.cvut.kbss.ontodriver.descriptor.SimpleListValueDescriptor;
24: import cz.cvut.kbss.ontodriver.exception.OntoDriverException;
25: import cz.cvut.kbss.ontodriver.model.Axiom;
26: import cz.cvut.kbss.ontodriver.model.NamedResource;
27:
28: import java.util.List;
29:
30: /**
31: * This interface is used to work with ontology sequences.
32: * <p>
33: * Currently, two kinds of sequences are supported:
34: * <ul>
35: * <li><b>Simple lists</b> - simple LISP-style singly-linked lists, where each node is the subject of a statement
36: * pointing to the next node,
37: * <li><b>Referenced lists</b> - lists, where each node points to the next element and also to its contents.
38: * </ul>
39: */
40: public interface Lists {
41:
42: /**
43: * Loads simple list specified by the descriptor.
44: * <p>
45: * The returned axioms should be iterable in the same order as they were put into the sequence in the ontology.
46: *
47: * @param descriptor Describes the list's properties as well as the context from which the list should be loaded.
48: * @return Axioms matching the specified list descriptor
49: * @throws OntoDriverException If an ontology access error occurs
50: * @throws IllegalStateException If called on a closed connection
51: */
52: List<Axiom<NamedResource>> loadSimpleList(SimpleListDescriptor descriptor) throws OntoDriverException;
53:
54: /**
55: * Persists simple list values specified by the descriptor.
56: * <p>
57: * The sequence is persisted in the order in which it appears in the descriptor.
58: *
59: * @param descriptor List values descriptor
60: * @throws OntoDriverException If an ontology access error occurs
61: * @throws IllegalStateException If called on a closed connection
62: */
63: void persistSimpleList(SimpleListValueDescriptor descriptor) throws OntoDriverException;
64:
65: /**
66: * Updates simple list based on values specified in the descriptor.
67: * <p>
68: * It is up to the driver implementation to decide whether the old list will be removed and the new values inserted
69: * or whether a merge will be performed.
70: *
71: * @param descriptor List values descriptor
72: * @throws OntoDriverException If an ontology access error occurs
73: * @throws IllegalStateException If called on a closed connection
74: */
75: void updateSimpleList(SimpleListValueDescriptor descriptor) throws OntoDriverException;
76:
77: /**
78: * Loads referenced list specified by the descriptor.
79: * <p>
80: * The returned axioms should be iterable in the same order as they were put into the sequence in the ontology.
81: *
82: * @param descriptor Describes list's properties, including node content assertion. Also may specify context from
83: * which the list should be loaded
84: * @return Axioms matching the specified list descriptor
85: * @throws OntoDriverException If an ontology access error occurs
86: * @throws IllegalStateException If called on a closed connection
87: */
88: List<Axiom<?>> loadReferencedList(ReferencedListDescriptor descriptor) throws OntoDriverException;
89:
90: /**
91: * Persists referenced list values specified by the descriptor.
92: * <p>
93: * The sequence is persisted in the order in which it appears in the descriptor.
94: *
95: * @param descriptor List values descriptor
96: * @throws OntoDriverException If an ontology access error occurs
97: * @throws IllegalStateException If called on a closed connection
98: */
99: <T> void persistReferencedList(ReferencedListValueDescriptor<T> descriptor) throws OntoDriverException;
100:
101: /**
102: * Updates referenced list based on the values in the specified list descriptor.
103: * <p>
104: * It is up to the driver implementation whether the update will be realized by removing the old list and persisting
105: * the new values, or by merging the new list into the old one.
106: *
107: * @param descriptor List values descriptor
108: * @throws OntoDriverException If an ontology access error occurs
109: * @throws IllegalStateException If called on a closed connection
110: */
111: <T> void updateReferencedList(ReferencedListValueDescriptor<T> descriptor) throws OntoDriverException;
112: }