Package: Lists

Lists

Coverage

1: /**
2: * Copyright (C) 2016 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. </p>
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 pointing to the next node,</li>
33: * <li><b>Referenced lists</b> - lists, where each node points to the next element and also to its contents.</li>
34: * </ul>
35: *
36: * @author kidney
37: */
38: public interface Lists {
39:
40: /**
41: * Loads simple list specified by the descriptor. </p>
42: * <p>
43: * The returned axioms should be iterable in the same order as they were put into the sequence in the ontology.
44: *
45: * @param descriptor Describes the list's properties as well as the context from which the list should be loaded.
46: * @return Axioms matching the specified list descriptor
47: * @throws OntoDriverException If an ontology access error occurs
48: * @throws IllegalStateException If called on a closed connection
49: */
50: List<Axiom<NamedResource>> loadSimpleList(SimpleListDescriptor descriptor) throws OntoDriverException;
51:
52: /**
53: * Persists simple list values specified by the descriptor. </p>
54: * <p>
55: * The sequence is persisted in the order in which it appears in the descriptor.
56: *
57: * @param descriptor List values descriptor
58: * @throws OntoDriverException If an ontology access error occurs
59: * @throws IllegalStateException If called on a closed connection
60: */
61: void persistSimpleList(SimpleListValueDescriptor descriptor) throws OntoDriverException;
62:
63: /**
64: * Updates simple list based on values specified in the descriptor. </p>
65: * <p>
66: * It is up to the driver implementation to decide whether the old list will be removed and the new values inserted
67: * or whether a merge will be performed.
68: *
69: * @param descriptor List values descriptor
70: * @throws OntoDriverException If an ontology access error occurs
71: * @throws IllegalStateException If called on a closed connection
72: */
73: void updateSimpleList(SimpleListValueDescriptor descriptor) throws OntoDriverException;
74:
75: /**
76: * Loads referenced list specified by the descriptor. </p>
77: * <p>
78: * The returned axioms should be iterable in the same order as they were put into the sequence in the ontology.
79: *
80: * @param descriptor Describes list's properties, including node content assertion. Also may specify context from
81: * which the list should be loaded
82: * @return Axioms matching the specified list descriptor
83: * @throws OntoDriverException If an ontology access error occurs
84: * @throws IllegalStateException If called on a closed connection
85: */
86: List<Axiom<NamedResource>> loadReferencedList(ReferencedListDescriptor descriptor) throws OntoDriverException;
87:
88: /**
89: * Persists referenced list values specified by the descriptor. </p>
90: * <p>
91: * The sequence is persisted in the order in which it appears in the descriptor.
92: *
93: * @param descriptor List values descriptor
94: * @throws OntoDriverException If an ontology access error occurs
95: * @throws IllegalStateException If called on a closed connection
96: */
97: void persistReferencedList(ReferencedListValueDescriptor descriptor) throws OntoDriverException;
98:
99: /**
100: * Updates referenced list based on the values in the specified list descriptor. </p>
101: * <p>
102: * It is up to the driver implementation whether the update will be realized by removing the old list and persisting
103: * the new values, or by merging the new list into the old one.
104: *
105: * @param descriptor List values descriptor
106: * @throws OntoDriverException If an ontology access error occurs
107: * @throws IllegalStateException If called on a closed connection
108: */
109: void updateReferencedList(ReferencedListValueDescriptor descriptor) throws OntoDriverException;
110: }