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 com.google.common.collect.ImmutableMap;
12 import java.io.IOException;
13 import org.opendaylight.yangtools.yang.common.QName;
14 import org.opendaylight.yangtools.yang.data.api.schema.stream.NormalizedNodeStreamWriter;
15 import org.opendaylight.yangtools.yang.data.api.schema.stream.NormalizedNodeStreamWriterExtension;
18 * Extension to the NormalizedNodeStreamWriter with metadata support. Semantically this extends the event model of
19 * {@link NormalizedNodeStreamWriter} with a new event, {@link #metadata(ImmutableMap)}. This event is valid on any
20 * open node. This event may be emitted only once.
23 * Note that some implementations of this interface, notably those targeting streaming XML, may require metadata to
24 * be emitted before any other events. Such requirement is communicated through {@link #requireMetadataFirst()} and
25 * users must honor it. If such requirement is not set, metadata may be emitted at any time.
28 * Furthermore implementations targeting RFC7952 encoding towards external systems are required to handle metadata
29 * attached to {@code leaf-list} and {@code list} nodes by correctly extending them to each entry.
32 public interface StreamWriterMetadataExtension extends NormalizedNodeStreamWriterExtension {
34 * Emit a block of metadata associated with the currently-open node. The argument is a map of annotation names,
35 * as defined {@code md:annotation} extension. Values are normalized objects, which are required to be
36 * effectively-immutable.
38 * @param metadata Metadata block
39 * @throws NullPointerException if {@code metadata} is null
40 * @throws IllegalStateException when this method is invoked outside of an open node or metadata has already been
42 * @throws IOException if an underlying IO error occurs
44 void metadata(ImmutableMap<QName, Object> metadata) throws IOException;
47 * Indicate whether metadata is required to be emitted just after an entry is open. The default implementation
50 * @return True if metadata must occur just after the start of an entry.
52 default boolean requireMetadataFirst() {