2 * Copyright (c) 2019 PANTHEON.tech, s.r.o. and others. All rights reserved.
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
6 * and is available at http://www.eclipse.org/legal/epl-v10.html
8 package org.opendaylight.yangtools.rfc7952.data.api;
10 import com.google.common.annotations.Beta;
11 import java.io.IOException;
12 import org.eclipse.jdt.annotation.NonNull;
13 import org.eclipse.jdt.annotation.Nullable;
14 import org.opendaylight.yangtools.rfc7952.model.api.AnnotationSchemaNode;
15 import org.opendaylight.yangtools.yang.common.QName;
16 import org.opendaylight.yangtools.yang.data.api.schema.stream.NormalizedNodeStreamWriter;
17 import org.opendaylight.yangtools.yang.data.api.schema.stream.NormalizedNodeStreamWriterExtension;
20 * Extension to the NormalizedNodeStreamWriter with metadata support. Semantically this extends the event model of
21 * {@link NormalizedNodeStreamWriter} with two new events:
23 * <li>{@link #startMetadata(int)} is within the scope of any open node and starts a block of metadata entries. It
24 * is recommended to emit this block before any other events. Only
25 * {@link #startMetadataEntry(QName, AnnotationSchemaNode)} and {@link NormalizedNodeStreamWriter#endNode()} are valid
26 * in this node. This event may be emitted at most once for any open node.
28 * <li>{@link #startMetadataEntry(QName, AnnotationSchemaNode)} to start a metadata entry. Its value is must be emitted
29 * via {@link NormalizedNodeStreamWriter#nodeValue(Object)} before the entry is closed via
30 * {@link NormalizedNodeStreamWriter#endNode()}.
34 * Note that some implementations of this interface, notably those targeting streaming XML, may require metadata to
35 * be emitted before any other events. Such requirement is communicated through {@link #requireMetadataFirst()} and
36 * users must honor it. If such requirement is not set, metadata may be emitted at any time.
39 * Furthermore implementations targeting RFC7952 encoding towards external systems are required to handle metadata
40 * attached to {@code leaf-list} and {@code list} nodes by correctly extending them to each entry.
43 public interface NormalizedMetadataStreamWriter extends NormalizedNodeStreamWriterExtension {
45 * Start the metadata block for the currently-open node. Allowed events are
46 * {@link #startMetadataEntry(QName, AnnotationSchemaNode)} and {@link NormalizedNodeStreamWriter#endNode()}.
48 * @param childSizeHint Non-negative count of expected direct child nodes or
49 * {@link NormalizedNodeStreamWriter#UNKNOWN_SIZE} if count is unknown. This is only hint and
50 * should not fail writing of child events, if there are more events than count.
51 * @throws IllegalStateException if current node already has a metadata block or cannot receive metadata -- for
52 * example because {@link #requireMetadataFirst()} was not honored.
53 * @throws IOException if an underlying IO error occurs
55 void startMetadata(int childSizeHint) throws IOException;
58 * Start a new metadata entry. The value of the metadata entry should be emitted through
59 * {@link NormalizedNodeStreamWriter#nodeValue(Object)}.
61 * @param name Metadata name, as defined through {@code md:annotation}
62 * @param schema Effective {@code md:annotation} schema, or null if unknown to the caller
63 * @throws NullPointerException if {@code name} is null
64 * @throws IllegalStateException when this method is invoked outside of a metadata block
65 * @throws IOException if an underlying IO error occurs
67 void startMetadataEntry(@NonNull QName name, @Nullable AnnotationSchemaNode schema) throws IOException;
70 * Indicate whether metadata is required to be emitted just after an entry is open. The default implementation
73 * @return True if metadata must occur just after the start of an entry.
75 default boolean requireMetadataFirst() {