Package: ObjectOntologyMapper

ObjectOntologyMapper

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.jopa.oom;
19:
20: import cz.cvut.kbss.jopa.model.descriptors.Descriptor;
21: import cz.cvut.kbss.jopa.model.metamodel.EntityType;
22: import cz.cvut.kbss.jopa.model.metamodel.FieldSpecification;
23: import cz.cvut.kbss.jopa.oom.exception.UnpersistedChangeException;
24: import cz.cvut.kbss.jopa.sessions.util.LoadingParameters;
25: import cz.cvut.kbss.ontodriver.model.Axiom;
26:
27: import java.net.URI;
28: import java.util.Set;
29:
30: public interface ObjectOntologyMapper {
31:
32: /**
33: * Checks whether the storage contains individual with the specified identifier and of the specified type.
34: *
35: * @param cls Class representing the individual type
36: * @param identifier Identifier
37: * @param descriptor Descriptor, can specify context
38: * @return {@code true} if the ontology contains such individual, {@code false} otherwise
39: */
40: <T> boolean containsEntity(Class<T> cls, URI identifier, Descriptor descriptor);
41:
42: /**
43: * Loads and reconstructs an entity from the ontology.
44: *
45: * @param loadingParameters Entity loading parameters
46: * @return Reconstructed entity or {@code null} if there is none such
47: */
48: <T> T loadEntity(LoadingParameters<T> loadingParameters);
49:
50: /**
51: * Gets a reference to an entity corresponding to the specified parameters.
52: * <p>
53: * The reference is an empty object with state fetched upon first access.
54: *
55: * @param loadingParameters Reference loading parameters
56: * @param <T> Entity type
57: * @return Entity reference
58: */
59: <T> T getReference(LoadingParameters<T> loadingParameters);
60:
61: /**
62: * Loads entity field value and sets it on the specified entity.
63: *
64: * @param entity The entity on which the field value will be set
65: * @param fieldSpec The field to load
66: * @param descriptor Descriptor possibly specifying the field context
67: */
68: <T> void loadFieldValue(T entity, FieldSpecification<? super T, ?> fieldSpec, Descriptor descriptor);
69:
70: /**
71: * Generates a fresh identifier for an instance of the specified entity type.
72: *
73: * @param et Entity type used as base for the identifier
74: * @return New entity identifier
75: */
76: URI generateIdentifier(EntityType<?> et);
77:
78: /**
79: * Persists the specified entity into the underlying ontology.
80: *
81: * @param identifier Identifier of the persisted entity, possibly {@code null}
82: * @param entity The entity to persist
83: * @param descriptor Descriptor possibly specifying entity and attribute contexts
84: */
85: <T> void persistEntity(URI identifier, T entity, Descriptor descriptor);
86:
87: /**
88: * Removes entity with specified identifier from the ontology.
89: *
90: * @param identifier Entity identifier
91: * @param cls Entity class
92: * @param descriptor Descriptor specifying entity attribute contexts
93: */
94: <T> void removeEntity(URI identifier, Class<T> cls, Descriptor descriptor);
95:
96: /**
97: * Checks that there are not any pending changes in the mapper.
98: *
99: * @throws UnpersistedChangeException Thrown when there are unpersisted changes
100: */
101: void checkForUnpersistedChanges();
102:
103: /**
104: * Sets value of property represented by the specified field to the field's value.
105: *
106: * @param entity Entity containing the field
107: * @param fieldSpec The field to update
108: * @param descriptor Optionally specifies context
109: */
110: <T> void updateFieldValue(T entity, FieldSpecification<? super T, ?> fieldSpec, Descriptor descriptor);
111:
112: /**
113: * Extracts the value of the specified field from the specified entity and transforms it to axioms.
114: *
115: * @param entity Entity to extract attribute from
116: * @param fieldSpec Field specification determining which values to extract
117: * @param entityDescriptor Entity descriptor
118: * @param <T> Entity type
119: * @return Set of axioms representing the field value
120: */
121: <T> Set<Axiom<?>> getAttributeAxioms(T entity, FieldSpecification<? super T, ?> fieldSpec,
122: Descriptor entityDescriptor);
123:
124: /**
125: * Checks if the specified attribute value of the specified entity is inferred in the repository.
126: * <p>
127: * Note that attribute context may be ignored by the underlying repository, based on its inference storing strategy.
128: * Also note that if the corresponding statement is both inferred and asserted, this method will return
129: * {@code true}.
130: *
131: * @param entity Entity whose attribute value to examine
132: * @param fieldSpec Field specification representing the property to examine
133: * @param value Value whose inference status to examine
134: * @param entityDescriptor Entity descriptor used to specify repository context
135: * @param <T> Entity type
136: * @return {@code true} if the value is inferred, {@code false} otherwise
137: */
138: <T> boolean isInferred(T entity, FieldSpecification<? super T, ?> fieldSpec, Object value,
139: Descriptor entityDescriptor);
140: }