Package: InstanceBuilder

InstanceBuilder

Coverage

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