Package: Descriptor

Descriptor

name	instruction	branch	complexity	line	method
overridesAssertionContext()	M: 0 C: 2 100%	M: 0 C: 0 100%	M: 0 C: 1 100%	M: 0 C: 1 100%	M: 0 C: 1 100%

Coverage

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