Package: InstanceBuilder

InstanceBuilder

Coverage

1: /**
2: * Copyright (C) 2022 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.jsonld.deserialization;
16:
17: import cz.cvut.kbss.jopa.model.annotations.OWLClass;
18: import cz.cvut.kbss.jopa.model.annotations.Types;
19: import cz.cvut.kbss.jsonld.common.CollectionType;
20: import cz.cvut.kbss.jsonld.exception.JsonLdDeserializationException;
21:
22: import java.util.List;
23: import java.util.Optional;
24:
25: /**
26: * Builds instances from parsed JSON-LD.
27: */
28: public interface InstanceBuilder {
29:
30: /**
31: * Creates new instance to fill filled mapped by the specified property.
32: * <p>
33: * The instance type is determined from the declared type of the mapped field, which is taken from the currently
34: * open object, and from the specified types. Therefore, another object has to be already open before this method
35: * can be called.
36: * <p>
37: * The new instance also becomes the currently open object.
38: * <p>
39: * This method should also verify cardinality, i.e. multiple objects cannot be set for the same property, if the
40: * field it maps to is singular.
41: * <p>
42: * This method assumes that the property is mapped, i.e. that {@link #isPropertyMapped(String)} returned true.
43: *
44: * @param id Identifier of the object being open
45: * @param property Property identifier (IRI)
46: * @param types Types of the object being open
47: * @throws IllegalStateException If there is no {@link OWLClass} instance open
48: */
49: void openObject(String id, String property, List<String> types);
50:
51: /**
52: * Creates new instance of the specified class.
53: * <p>
54: * If there is a collection currently open, it adds the new instance to it.
55: * <p>
56: * The new instance also becomes the currently open object.
57: * <p>
58: * This method is intended for creating top level objects or adding objects to collections. Use {@link
59: * #openObject(String, String, List)} for opening objects as values of attributes.
60: *
61: * @param <T> The type of the object to open
62: * @param id Identifier of the object being open
63: * @param cls Java type of the object being open
64: * @see #openObject(String, String, List)
65: */
66: <T> void openObject(String id, Class<T> cls);
67:
68: /**
69: * Closes the most recently open object.
70: */
71: void closeObject();
72:
73: /**
74: * Creates new instance of appropriate collection and sets it as value of the specified property of the currently
75: * open object.
76: * <p>
77: * The collection type is determined from the declared type of the mapped field, which is taken from the currently
78: * open object. Therefore, another object has to be already open before this method can be called.
79: * <p>
80: * The new collection also becomes the currently open object.
81: * <p>
82: * This method should also verify cardinality, i.e. a collection cannot be set as value of a field mapped by {@code
83: * property}, if the field is singular.
84: * <p>
85: * This method assumes that the property is mapped, i.e. that {@link #isPropertyMapped(String)} returned true.
86: *
87: * @param property Property identifier (IRI)
88: * @throws IllegalStateException If there is no {@link OWLClass} instance open
89: */
90: void openCollection(String property);
91:
92: /**
93: * Creates new instance of the specified collection type.
94: * <p>
95: * If there is a collection currently open, it adds the new collection as its new item.
96: * <p>
97: * The new collection also becomes the currently open object.
98: * <p>
99: * This method is intended for creating top level collections or nesting collections. Use {@link
100: * #openCollection(String)} for opening collections as values of attributes.
101: *
102: * @param collectionType Type of the JSON collection to instantiate in Java
103: * @see #openCollection(String)
104: */
105: void openCollection(CollectionType collectionType);
106:
107: /**
108: * Closes the most recently open collection.
109: */
110: void closeCollection();
111:
112: /**
113: * Adds the specified value of the specified property to the currently open object.
114: * <p>
115: * This method is intended for non-composite JSON values like String, Number Boolean and {@code null}. It can also
116: * handle IRIs of objects already parsed by the deserializer, which are serialized as Strings in JSON-LD. In this
117: * case, the field is filled with the deserialized object.
118: * <p>
119: * This method should also verify cardinality and correct typing, e.g. multiple values cannot be set for the same
120: * property, if the field it maps to is singular.
121: * <p>
122: * This method assumes that the property is mapped, i.e. that {@link #isPropertyMapped(String)} returned true.
123: *
124: * @param property Property identifier (IRI)
125: * @param value The value to set
126: * @throws IllegalStateException If there is no {@link OWLClass} instance open
127: */
128: void addValue(String property, Object value);
129:
130: /**
131: * Adds the specified value to the currently open collection.
132: * <p>
133: * This method is intended for non-composite JSON values like String, Number Boolean and {@code null}. It can also
134: * handle IRIs of objects already parsed by the deserializer, which are serialized as Strings in JSON-LD. In this
135: * case, the deserialized object is added to the collection.
136: *
137: * @param value The value to add
138: */
139: void addValue(Object value);
140:
141: /**
142: * Adds a reference to a node to the currently open object.
143: * <p>
144: * This methods is invoked in case the deserializer encounters an object with a single attribute - @id. This assumes
145: * that the node either references an already encountered object (known instance) or that the node is a value of a
146: * plain identifier-valued object property.
147: * <p>
148: * This method should also verify cardinality and correct typing, e.g. multiple values cannot be set for the same
149: * property, if the field it maps to is singular.
150: * <p>
151: * It is assumed that the property is mapped, i.e. that {@link #isPropertyMapped(String)} returned true.
152: *
153: * @param property Property identifier (IRI)
154: * @param nodeId Identifier (IRI) of the node, i.e. value of the @id attribute
155: */
156: void addNodeReference(String property, String nodeId);
157:
158: /**
159: * Adds the specified value to the currently open collection.
160: * <p>
161: * This methods is invoked in case the deserializer encounters an object with a single attribute - @id. This assumes
162: * that the node either references an already encountered object (known instance) or that the node is a value of a
163: * plain identifier-valued object property.
164: *
165: * @param nodeId Identifier (IRI) of the node, i.e. value of the @id attribute
166: */
167: void addNodeReference(String nodeId);
168:
169: /**
170: * Returns current root of the deserialized object graph.
171: *
172: * @return Object graph root, it can be a {@link OWLClass} instance, or a {@link java.util.Collection}
173: */
174: Object getCurrentRoot();
175:
176: /**
177: * Returns the declared type of elements of the current instance, if it is a collection.
178: *
179: * @return Collection element type
180: * @throws JsonLdDeserializationException If the current instance is not a collection
181: */
182: Class<?> getCurrentCollectionElementType();
183:
184: /**
185: * Checks whether the current collection context represents a {@link cz.cvut.kbss.jopa.model.annotations.Properties}
186: * attribute.
187: *
188: * @return {@code true} if the current context is a collection representing a {@link
189: * cz.cvut.kbss.jopa.model.annotations.Properties} field
190: */
191: boolean isCurrentCollectionProperties();
192:
193: /**
194: * Gets the Java type of the current object context.
195: *
196: * @return Java class of the instance currently being built
197: */
198: Class<?> getCurrentContextType();
199:
200: /**
201: * Checks whether the specified property is mapped to a plural field.
202: * <p>
203: * This method assumes that the property is mapped, i.e. that {@link #isPropertyMapped(String)} returned true.
204: * <p>
205: * Note that {@link Types} and {@link cz.cvut.kbss.jopa.model.annotations.Properties} fields are always treated as
206: * plural.
207: *
208: * @param property Property identifier (IRI)
209: * @return Whether mapped field is collection-valued or not
210: */
211: boolean isPlural(String property);
212:
213: /**
214: * Checks whether the specified property is mapped by the class representing the current instance context.
215: * <p>
216: * Returns true also for the {@link cz.cvut.kbss.jsonld.JsonLd#TYPE} property, even though the target instance may
217: * not contain a {@link Types} field. The builder has to be able to handle types no matter whether a types field is
218: * present or not.
219: *
220: * @param property Property identifier (IRI)
221: * @return Whether the property is mapped in the current instance context
222: */
223: boolean isPropertyMapped(String property);
224:
225: /**
226: * Checks whether the specified property can be deserialized.
227: * <p>
228: * A property cannot be deserialized if it is not mapped or if the mapped field's access is read-only.
229: *
230: * @param property Property identifier (IRI)
231: * @return Whether property can be deserialized
232: * @see #isPropertyMapped(String)
233: * @see cz.cvut.kbss.jsonld.annotation.JsonLdProperty.Access#READ_ONLY
234: */
235: boolean isPropertyDeserializable(String property);
236:
237: /**
238: * Gets the target type of the specified property.
239: *
240: * That is, it retrieves the type of the field to which the specified property is mapped. If the target field is a collection,
241: * the element type is returned (equivalent to {@link #getCurrentCollectionElementType()}).
242: *
243: * This method assumes that the property is mapped, i.e. that {@link #isPropertyMapped(String)} returned true.
244: * @param property Property whose target type to resolve
245: * @return Target type wrapped in an optional
246: */
247: Class<?> getTargetType(String property);
248: }