Package: InstanceBuilder

InstanceBuilder

Coverage

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