Method: overridesAssertionContext()

1: /*
2: * JOPA
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.jopa.model.descriptors;
19:
20: import cz.cvut.kbss.jopa.exceptions.AmbiguousContextException;
21: import cz.cvut.kbss.jopa.model.metamodel.FieldSpecification;
22:
23: import java.net.URI;
24: import java.util.Collection;
25: import java.util.Optional;
26: import java.util.Set;
27:
28: /**
29: * Used to specify additional metadata for entities and their attributes.
30: * <p>
31: * Descriptors are composed in a hierarchical structure representing the object graph they describe.
32: */
33: public interface Descriptor {
34:
35: /**
36: * Gets contexts for this descriptor.
37: * <p>
38: * An empty result indicates the default context.
39: * <p>
40: * Note that for saving, there must be at most one context.
41: *
42: * @return Context URIs
43: */
44: Set<URI> getContexts();
45:
46: /**
47: * Gets the only context specified by this descriptor.
48: * <p>
49: * This method will check whether there is at most one context specified in this descriptor. If there are none
50: * (meaning the default should be used), an empty {@link Optional} is returned. If there are more than one, an
51: * {@link AmbiguousContextException} is thrown.
52: * <p>
53: * This method is intended to be used by data modification operations, which require at most one target context to
54: * be specified.
55: *
56: * @return Single entity context wrapped in {@code Optional}, empty, if there is none
57: * @throws AmbiguousContextException If there are more than one context specified
58: */
59: Optional<URI> getSingleContext();
60:
61: /**
62: * Adds the specified context to this descriptor.
63: * <p>
64: * Note that adding the default context removes all the previously added contexts, as they become obsolete.
65: *
66: * @param context Context to add, {@code null} indicates default context
67: * @return This instance
68: */
69: Descriptor addContext(URI context);
70:
71: /**
72: * Gets the language set for this descriptor.
73: *
74: * @return Language tag (e.g. en, cs), can be {@code null}, meaning any language is supported or the language tag
75: * has not been set (see {@link #hasLanguage()})
76: */
77: String getLanguage();
78:
79: /**
80: * Gets information about whether language tag has been set on this descriptor.
81: * <p>
82: * The language tag can be explicitly set to {@code null}, meaning any language is supported. This can be used to
83: * override PU-level language setting.
84: *
85: * @return {@code true} if a language tag has been set on this descriptor, {@code false} otherwise
86: */
87: boolean hasLanguage();
88:
89: /**
90: * Sets language tag of this descriptor.
91: * <p>
92: * Applies to any possible sub-descriptors as well.
93: *
94: * @param languageTag The language tag to use, possibly {@code null}, meaning no language preference should be used
95: * @return This instance
96: * @see #anyLanguage()
97: */
98: Descriptor setLanguage(String languageTag);
99:
100: /**
101: * Configures this descriptor to support any language tag (including no language tags).
102: * <p>
103: * This is useful for overriding previously set language tag expectations (either on PU level or parent descriptor
104: * level).
105: * <p>
106: * This does the same as calling {@link #setLanguage(String)} with {@code null} argument, but is more explicit.
107: *
108: * @return This instance
109: */
110: Descriptor anyLanguage();
111:
112: /**
113: * Gets attribute descriptors specified in this descriptor.
114: *
115: * @return Unmodifiable view of attribute descriptors
116: */
117: Collection<Descriptor> getAttributeDescriptors();
118:
119: /**
120: * Gets descriptor for the specified attribute.
121: *
122: * @param attribute Entity attribute, as specified by the application metamodel
123: * @return Descriptor
124: * @throws IllegalArgumentException If the descriptor is not available
125: */
126: Descriptor getAttributeDescriptor(FieldSpecification<?, ?> attribute);
127:
128: /**
129: * Gets contexts in which the property assertion(s) of the specified attribute are stored.
130: * <p>
131: * If none are specified for the attribute, contexts of this descriptor are returned.
132: * <p>
133: * Note that for saving a property assertion, there must be at most one context.
134: *
135: * @param attribute Entity attribute, as specified by the application model
136: * @return Context identifiers
137: */
138: Set<URI> getAttributeContexts(FieldSpecification<?, ?> attribute);
139:
140: /**
141: * Gets the only context specified by this descriptor for the specified attribute.
142: * <p>
143: * If no context is specified (meaning the default context should be used), an empty {@link Optional} is returned.
144: * <p>
145: * If more than one context are available for the specified attribute, an {@link AmbiguousContextException} is
146: * thrown.
147: *
148: * @param attribute Entity attribute, as specified by the application model
149: * @return Context identifier
150: * @throws AmbiguousContextException If a unique attribute context cannot be determined
151: * @see #getAttributeContexts(FieldSpecification)
152: */
153: Optional<URI> getSingleAttributeContext(FieldSpecification<?, ?> attribute);
154:
155: /**
156: * Adds descriptor for the specified attribute.
157: * <p>
158: * If a descriptor already exists for the specified attribute, it is overridden by the new one.
159: *
160: * @param attribute The attribute to set descriptor for
161: * @param descriptor The descriptor to use
162: * @return This instance
163: */
164: Descriptor addAttributeDescriptor(FieldSpecification<?, ?> attribute, Descriptor descriptor);
165:
166: /**
167: * Adds repository context for the specified attribute.
168: * <p>
169: * This in effect means creating a descriptor (if it does not already exist) for the specified field and adding the
170: * specified context to it.
171: *
172: * @param attribute The attribute to set context for
173: * @param context The context to set
174: * @return This instance
175: * @see #addAttributeDescriptor(FieldSpecification, Descriptor)
176: */
177: Descriptor addAttributeContext(FieldSpecification<?, ?> attribute, URI context);
178:
179: /**
180: * Sets language to be used when working (retrieving, persisting) with values of the specified attribute.
181: * <p>
182: * Note that setting language in this manner will not have any effect on descriptors of the specified attribute
183: * previously retrieved from this descriptor.
184: *
185: * @param attribute The attribute concerned
186: * @param languageTag Language tag to use, possibly {@code null}
187: * @return This instance
188: */
189: Descriptor setAttributeLanguage(FieldSpecification<?, ?> attribute, String languageTag);
190:
191: /**
192: * Whether property assertion should be stored in the subject's context (default), or whether they should be stored
193: * together with the assertion value.
194: * <p>
195: * This applies to object references, literal values are always stored in the specified context.
196: *
197: * @return Whether property assertion is stored in the subject context
198: */
199: boolean areAssertionsInSubjectContext();
200:
201: /**
202: * Whether this descriptor overrides assertion context.
203: * <p>
204: * Assertions are typically stored in the subject context, even if their target is in a different context (see
205: * {@link #areAssertionsInSubjectContext()}). However, literal values have to be stored in the assertion context
206: * only, so descriptors of fields holding literal values can override the default assertion target context to use
207: * the field descriptor context for assertion as well.
208: *
209: * @return Boolean indicating whether assertion context is based on object descriptor
210: * @see #areAssertionsInSubjectContext()
211: */
212: default boolean overridesAssertionContext() {
213: return false;
214: }
215:
216: /**
217: * Whether to include inferred statements when loading data corresponding to this descriptor.
218: * <p>
219: * Note that this setting is taken into account only for attributes that are declared as possibly containing
220: * inferred values (using the {@link cz.cvut.kbss.jopa.model.annotations.Inferred} annotation). For explicit
221: * attributes, this setting is ignored.
222: * <p>
223: * The setting in this descriptor is applied recursively to all the descriptors it may be composed of, unless a
224: * different value is specified explicitly for them.
225: *
226: * @return Whether to include inferred values for inferred attributes
227: * @see #disableInference()
228: * @see #enableInference()
229: */
230: boolean includeInferred();
231:
232: /**
233: * Instructs this descriptor to specify that only asserted statements should be loaded for otherwise inferred
234: * attributes.
235: *
236: * @return This descriptor
237: * @see #includeInferred()
238: */
239: Descriptor disableInference();
240:
241: /**
242: * Instructs this descriptor to specify that both inferred and asserted statements should be loaded for otherwise
243: * inferred attributes.
244: * <p>
245: * This is the default setting.
246: *
247: * @return This descriptor
248: * @see #includeInferred()
249: */
250: Descriptor enableInference();
251: }