Package: Lists

Lists

Coverage

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