Package: InstanceBuilder

InstanceBuilder

Coverage

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