binding/mdsal-binding-dom-codec/src/main/java/org/opendaylight/mdsal/binding/dom/codec/api/BindingNormalizedNodeWriterFactory.java

   1 /*
   2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   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
   7  */
   8 package org.opendaylight.mdsal.binding.dom.codec.api;
   9
  10 import java.util.Map.Entry;
  11 import org.eclipse.jdt.annotation.NonNull;
  12 import org.opendaylight.yangtools.yang.binding.Action;
  13 import org.opendaylight.yangtools.yang.binding.BindingStreamEventWriter;
  14 import org.opendaylight.yangtools.yang.binding.DataContainer;
  15 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  16 import org.opendaylight.yangtools.yang.binding.Notification;
  17 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  18 import org.opendaylight.yangtools.yang.data.api.schema.stream.NormalizedNodeStreamWriter;
  19
  20 /**
  21  * Factory for {@link BindingStreamEventWriter}, which provides stream writers which translates data and delegates
  22  * calls to {@link NormalizedNodeStreamWriter}.
  23  */
  24 public interface BindingNormalizedNodeWriterFactory {
  25     /**
  26      * Creates a {@link BindingStreamEventWriter} for data tree path which will translate to NormalizedNode model
  27      * and invoke proper events on supplied {@link NormalizedNodeStreamWriter}.
  28      *
  29      * <p>
  30      * Also provides translation of supplied Instance Identifier to {@link YangInstanceIdentifier} so client code, does
  31      * not need to translate that separately.
  32      *
  33      * <p>
  34      * If {@link YangInstanceIdentifier} is not needed, please use
  35      * {@link #newWriter(InstanceIdentifier, NormalizedNodeStreamWriter)} method to conserve resources.
  36      *
  37      * @param path
  38      *            Binding Path in conceptual data tree, for which writer should
  39      *            be instantiated
  40      * @param domWriter
  41      *            Stream writer on which events will be invoked.
  42      * @return Instance Identifier and {@link BindingStreamEventWriter}
  43      *         which will write to supplied {@link NormalizedNodeStreamWriter}.
  44      * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
  45      */
  46     @NonNull Entry<YangInstanceIdentifier, BindingStreamEventWriter> newWriterAndIdentifier(
  47             @NonNull InstanceIdentifier<?> path, @NonNull NormalizedNodeStreamWriter domWriter);
  48
  49     /**
  50      * Creates a {@link BindingStreamEventWriter} for data tree path which will translate to NormalizedNode model
  51      * and invoke proper events on supplied {@link NormalizedNodeStreamWriter}.
  52      *
  53      * <p>
  54      * This variant does not provide YANG instance identifier and is useful for use-cases, where
  55      * {@link InstanceIdentifier} translation is done in other way, or YANG instance identifier is unnecessary
  56      * (e.g. notifications, RPCs).
  57      *
  58      * @param path Binding Path in conceptual data tree, for which writer should
  59      *            be instantiated
  60      * @param domWriter Stream writer on which events will be invoked.
  61      * @return {@link BindingStreamEventWriter}
  62      *         which will write to supplied {@link NormalizedNodeStreamWriter}.
  63      * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
  64      */
  65     @NonNull BindingStreamEventWriter newWriter(@NonNull InstanceIdentifier<?> path,
  66             @NonNull NormalizedNodeStreamWriter domWriter);
  67
  68     /**
  69      * Creates a {@link BindingStreamEventWriter} for RPC data which will translate to NormalizedNode model and invoke
  70      * proper events on supplied {@link NormalizedNodeStreamWriter}.
  71      *
  72      * @param rpcInputOrOutput Binding class representing RPC input or output,
  73      *            for which writer should be instantiated
  74      * @param domWriter
  75      *            Stream writer on which events will be invoked.
  76      * @return {@link BindingStreamEventWriter} which will write to supplied
  77      *         {@link NormalizedNodeStreamWriter}.
  78      */
  79     @NonNull BindingStreamEventWriter newRpcWriter(@NonNull Class<? extends DataContainer> rpcInputOrOutput,
  80             @NonNull NormalizedNodeStreamWriter domWriter);
  81
  82     /**
  83      * Creates a {@link BindingStreamEventWriter} for notification which will translate to NormalizedNode model
  84      * and invoke proper events on supplied {@link NormalizedNodeStreamWriter}.
  85      *
  86      * @param notification Binding class representing notification,
  87      *            for which writer should be instantiated
  88      * @param domWriter
  89      *            Stream writer on which events will be invoked.
  90      * @return {@link BindingStreamEventWriter} which will write to supplied
  91      *         {@link NormalizedNodeStreamWriter}.
  92      */
  93     @NonNull BindingStreamEventWriter newNotificationWriter(@NonNull Class<? extends Notification> notification,
  94             @NonNull NormalizedNodeStreamWriter domWriter);
  95
  96     /**
  97      * Creates a {@link BindingStreamEventWriter} for action input which will translate to NormalizedNode model
  98      * and invoke proper events on supplied {@link NormalizedNodeStreamWriter}.
  99      *
 100      * @param action Binding class representing action for which writer should be instantiated
 101      * @param domWriter Stream writer on which events will be invoked.
 102      * @return {@link BindingStreamEventWriter} which will write to supplied {@link NormalizedNodeStreamWriter}.
 103      */
 104     @NonNull BindingStreamEventWriter newActionInputWriter(@NonNull Class<? extends Action<?, ?, ?>> action,
 105             @NonNull NormalizedNodeStreamWriter domWriter);
 106
 107     /**
 108      * Creates a {@link BindingStreamEventWriter} for action output which will translate to NormalizedNode model
 109      * and invoke proper events on supplied {@link NormalizedNodeStreamWriter}.
 110      *
 111      * @param action Binding class representing action for which writer should be instantiated
 112      * @param domWriter Stream writer on which events will be invoked.
 113      * @return {@link BindingStreamEventWriter} which will write to supplied {@link NormalizedNodeStreamWriter}.
 114      */
 115     @NonNull BindingStreamEventWriter newActionOutputWriter(@NonNull Class<? extends Action<?, ?, ?>> action,
 116             @NonNull NormalizedNodeStreamWriter domWriter);
 117 }