From 85d32b48ba1bf1a37a340fce81708f9bfd9080e4 Mon Sep 17 00:00:00 2001 From: Jakub Toth Date: Wed, 31 May 2017 11:12:10 +0200 Subject: [PATCH] Binding v2 DOM Codec - codecs API - Part 1 * normalized node codec * tree codec * tree node codec Change-Id: Id58cf84d337ce310afb889c54f913fdbb59d79b0 Signed-off-by: Jakub Toth --- .../BindingNormalizedNodeCachingCodec.java | 36 ++++ .../codecs/BindingNormalizedNodeCodec.java | 45 +++++ .../codec/api/codecs/BindingTreeCodec.java | 57 ++++++ .../api/codecs/BindingTreeNodeCodec.java | 163 ++++++++++++++++++ 4 files changed, 301 insertions(+) create mode 100644 binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingNormalizedNodeCachingCodec.java create mode 100644 binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingNormalizedNodeCodec.java create mode 100644 binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingTreeCodec.java create mode 100644 binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingTreeNodeCodec.java diff --git a/binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingNormalizedNodeCachingCodec.java b/binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingNormalizedNodeCachingCodec.java new file mode 100644 index 0000000000..56f7634d1b --- /dev/null +++ b/binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingNormalizedNodeCachingCodec.java @@ -0,0 +1,36 @@ +/* + * Copyright (c) 2017 Pantheon Technologies s.r.o. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.mdsal.binding.javav2.dom.codec.api.codecs; + +import com.google.common.annotations.Beta; +import org.opendaylight.mdsal.binding.javav2.spec.base.TreeNode; + +/** + * Caching variant of Binding to Normalized Node codec. + * + * Caching may introduce performance penalty to serialization / deserialization + * but may decrease use of heap for repetitive objects. + * + * @param + * - Binding representation of data + */ +@Beta +public interface BindingNormalizedNodeCachingCodec + extends BindingNormalizedNodeCodec, AutoCloseable { + + /** + * Invoking close will invalidate this codec and any of its child codecs and + * will invalidate cache. + * + * Any subsequent calls to this codec will fail with + * {@link IllegalStateException} thrown. + */ + @Override + void close(); +} + diff --git a/binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingNormalizedNodeCodec.java b/binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingNormalizedNodeCodec.java new file mode 100644 index 0000000000..52c5ccc9d8 --- /dev/null +++ b/binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingNormalizedNodeCodec.java @@ -0,0 +1,45 @@ +/* + * Copyright (c) 2017 Pantheon Technologies s.r.o. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.mdsal.binding.javav2.dom.codec.api.codecs; + +import com.google.common.annotations.Beta; +import javax.annotation.Nonnull; +import org.opendaylight.mdsal.binding.javav2.spec.base.TreeNode; +import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; + +/** + * Codec providing serialization and deserializiation between Binding and + * NormalizedNode representation of data. + * + * + * @param + * - Binding representation of data + */ +@Beta +public interface BindingNormalizedNodeCodec { + + /** + * Converts from Normalized Node to Binding representation of data. + * + * @param data + * - Normalized Node representation of data + * @return Binding representation of data + */ + @Nonnull + T deserialize(@Nonnull NormalizedNode data); + + /** + * Converts from Binding to Normalized Node representation of data. + * + * @param data + * - Binding representation of data + * @return Normalized Node representation of data + */ + @Nonnull + NormalizedNode serialize(@Nonnull T data); +} \ No newline at end of file diff --git a/binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingTreeCodec.java b/binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingTreeCodec.java new file mode 100644 index 0000000000..a8962e23b7 --- /dev/null +++ b/binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingTreeCodec.java @@ -0,0 +1,57 @@ +/* + * Copyright (c) 2017 Pantheon Technologies s.r.o. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.mdsal.binding.javav2.dom.codec.api.codecs; + +import com.google.common.annotations.Beta; +import javax.annotation.Nullable; +import org.opendaylight.mdsal.binding.javav2.spec.base.InstanceIdentifier; +import org.opendaylight.mdsal.binding.javav2.spec.base.TreeNode; +import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier; +import org.opendaylight.yangtools.yang.model.api.SchemaPath; + +/** + * Navigable tree representing hierarchy of Binding to Normalized Node codecs. + * + * This navigable tree is associated to concrete set of YANG models, represented + * by SchemaContext and provides access to subtree specific serialization + * context. + */ +@Beta +public interface BindingTreeCodec { + + /** + * Get specific subtree serialization context by Binding path. + * + * @param path + * - {@link InstanceIdentifier} path + * @return subtree codec + */ + @Nullable + BindingTreeNodeCodec getSubtreeCodec(InstanceIdentifier path); + + /** + * Get specific subtree serialization context by DOM path. + * + * @param path + * - {@link YangInstanceIdentifier} path + * @return subtree codec + */ + @Nullable + BindingTreeNodeCodec getSubtreeCodec(YangInstanceIdentifier path); + + /** + * Get specific subtree serialization context by {@link SchemaPath} path. + * + * @param path + * - {@link SchemaPath} path + * @return specific subtree codec + */ + @Nullable + BindingTreeNodeCodec getSubtreeCodec(SchemaPath path); + +} diff --git a/binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingTreeNodeCodec.java b/binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingTreeNodeCodec.java new file mode 100644 index 0000000000..1e1011798e --- /dev/null +++ b/binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/codecs/BindingTreeNodeCodec.java @@ -0,0 +1,163 @@ +/* + * Copyright (c) 2017 Pantheon Technologies s.r.o. and others. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v1.0 which accompanies this distribution, + * and is available at http://www.eclipse.org/legal/epl-v10.html + */ +package org.opendaylight.mdsal.binding.javav2.dom.codec.api.codecs; + +import com.google.common.annotations.Beta; +import com.google.common.base.Optional; +import com.google.common.collect.ImmutableCollection; +import java.util.List; +import javax.annotation.Nonnull; +import javax.annotation.Nullable; +import org.opendaylight.mdsal.binding.javav2.spec.base.TreeArgument; +import org.opendaylight.mdsal.binding.javav2.spec.base.TreeNode; +import org.opendaylight.mdsal.binding.javav2.spec.runtime.BindingStreamEventWriter; +import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier; +import org.opendaylight.yangtools.yang.data.api.schema.stream.NormalizedNodeStreamWriter; + +/** + * Specific subtree codec to model subtree between Java Binding and DOM. + * + * @param + * - Binding representation of data + */ +@Beta +public interface BindingTreeNodeCodec extends BindingNormalizedNodeCodec { + + /** + * Returns binding class of interface which represents API of current schema + * node. + * + * @return interface which defines API of binding representation of data. + */ + @Nonnull + Class getBindingClass(); + + /** + * Returns child context as if it was walked by + * {@link BindingStreamEventWriter}. This means that to enter case, one must + * issue getChild(ChoiceClass).getChild(CaseClass). + * + * @param childClass + * - child class by Biding Stream navigation + * @return context of child + * @throws IllegalArgumentException + * - if supplied child class is not valid in specified context + */ + @Nonnull + BindingTreeNodeCodec streamChild(@Nonnull Class childClass); + + /** + * Returns child context as if it was walked by + * {@link BindingStreamEventWriter}. This means that to enter case, one must + * issue getChild(ChoiceClass).getChild(CaseClass). + * + * This method differs from {@link #streamChild(Class)}, that is less + * stricter for interfaces representing augmentation and cases, that may + * return {@link BindingTreeNodeCodec} even if augmentation interface + * containing same data was supplied and does not represent augmentation of + * this node. + * + * @param childClass + * - child class by Binding Stream navigation + * @return context of child or Optional absent if supplied is not applicable + * in context + */ + Optional> possibleStreamChild(@Nonnull Class childClass); + + /** + * Returns nested node context using supplied YANG Instance Identifier. + * + * @param child + * - Yang Instance Identifier Argument + * @return context of child + * @throws IllegalArgumentException + * - if supplied argument does not represent valid child + */ + @Nonnull + BindingTreeNodeCodec yangPathArgumentChild(@Nonnull YangInstanceIdentifier.PathArgument child); + + /** + * Returns nested node context using supplied Binding Instance Identifier + * and adds YANG instance identifiers to supplied list. + * + * @param arg + * - Binding Instance Identifier Argument + * @param builder + * - mutable instance of list, which is appended by + * YangInstanceIdentifiers as tree is walked, use null if such + * side-product is not needed + * @return context of child + * @throws IllegalArgumentException + * - if supplied argument does not represent valid child. + */ + @Nonnull + BindingTreeNodeCodec bindingPathArgumentChild(@Nonnull TreeArgument arg, + @Nullable List builder); + + /** + * Returns codec which uses caches serialization / deserialization results. + * + * Caching may introduce performance penalty to serialization / + * deserialization but may decrease use of heap for repetitive objects. + * + * @param cacheSpecifier + * - set of objects, for which cache may be in place + * @return codec which uses cache for serialization / deserialization + */ + @Nonnull + BindingNormalizedNodeCachingCodec + createCachingCodec(@Nonnull ImmutableCollection> cacheSpecifier); + + /** + * Writes data representing object to supplied stream. + * + * @param data + * - representing object + * @param writer + * - supplied stream + */ + void writeAsNormalizedNode(T data, NormalizedNodeStreamWriter writer); + + /** + * Serializes path argument for current node. + * + * @param arg + * - Binding Path Argument, may be null if Binding Instance + * Identifier does not have representation for current node (e.g. + * choice or case) + * @return Yang Path Argument, may be null if Yang Instance Identifier does + * not have representation for current node (e.g. case). + * @throws IllegalArgumentException + * - if supplied {@code arg} is not valid. + */ + @Nullable + YangInstanceIdentifier.PathArgument serializePathArgument(@Nullable TreeArgument arg); + + /** + * Deserializes path argument for current node. + * + * @param arg + * - Yang Path Argument, may be null if Yang Instance Identifier + * does not have representation for current node (e.g. case) + * @return Binding Path Argument, may be null if Binding Instance Identifier + * does not have representation for current node (e.g. choice or + * case) + * @throws IllegalArgumentException + * - if supplied {@code arg} is not valid. + */ + @Nullable + TreeArgument deserializePathArgument(@Nullable YangInstanceIdentifier.PathArgument arg); + + /** + * Return schema of node codec context. + * + * @return {@link Object} as schema of specific node context + */ + @Nonnull + Object getSchema(); +} -- 2.36.6