Package: InstanceBuilder

InstanceBuilder

Coverage

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