opendaylight/md-sal/sal-binding-broker/src/main/java/org/opendaylight/controller/sal/binding/codegen/RuntimeCodeGenerator.java

   1 package org.opendaylight.controller.sal.binding.codegen;
   2
   3 import org.opendaylight.controller.sal.binding.spi.DelegateProxy;
   4 import org.opendaylight.controller.sal.binding.spi.RpcRouter;
   5 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
   6 import org.opendaylight.yangtools.yang.binding.RpcService;
   7 import org.opendaylight.yangtools.yang.binding.annotations.RoutingContext;
   8
   9 public interface RuntimeCodeGenerator {
  10
  11     /**
  12      * Returns an instance of provided RpcService type which delegates all calls
  13      * to the delegate.
  14      *
  15      * <p>
  16      * Returned instance:
  17      * <ul>
  18      * <li>implements provided subclass of RpcService type and
  19      * {@link DelegateProxy} interface.
  20      * <li>
  21      * <p>
  22      * delegates all invocations of methods, which are defined in RpcService
  23      * subtype to delegate which is defined by
  24      * {@link DelegateProxy#setDelegate(Object)}.
  25      * <p>
  26      * If delegate is not defined (<code>getDelegate() == null</code>)
  27      * implementation throws {@link IllegalStateException}
  28      * <li>{@link DelegateProxy#getDelegate()} - returns the delegate to which
  29      * all calls are delegated.
  30      * <li>{@link DelegateProxy#setDelegate(Object)} - sets the delegate for
  31      * particular instance
  32      *
  33      * </ul>
  34      *
  35      * @param serviceType
  36      *            - Subclass of RpcService for which direct proxy is to be
  37      *            generated.
  38      * @return Instance of RpcService of provided serviceType which implements
  39      *         and {@link DelegateProxy}
  40      * @throws IllegalArgumentException
  41      *
  42      */
  43     <T extends RpcService> T getDirectProxyFor(Class<T> serviceType) throws IllegalArgumentException;
  44
  45     /**
  46      * Returns an instance of provided RpcService type which routes all calls to
  47      * other instances selected on particular input field.
  48      *
  49      * <p>
  50      * Returned instance:
  51      * <ul><li>Implements:
  52      *     <ul><li>{@link DelegateProxy}
  53      *         <li>{@link RpcRouter}
  54      *     </ul>
  55      *     <li>
  56      *     routes all invocations of methods, which are defined in RpcService
  57      *     subtype based on method arguments and routing information defined in the
  58      *     RpcRoutingTables for this instance
  59      *     {@link RpcRouter#getRoutingTable(Class)}.
  60      *     <ul>
  61      *     <li>
  62      *     Implementation uses
  63      *     {@link RpcRouter#getService(Class, InstanceIdentifier)} method to
  64      *     retrieve particular instance to which call will be routed.
  65      *    <li>
  66      *    Instance of {@link InstanceIdentifier} is determined by first argument of
  67      *    method and is retrieved via method which is annotated with
  68      *    {@link RoutingContext}. Class representing Routing Context Identifier is
  69      *    retrieved by {@link RoutingContext}.
  70      *    <li>If first argument is not defined / {@link RoutingContext} annotation
  71      *    is not present on any field invocation will be delegated to default
  72      *    service {@link RpcRouter#getDefaultService()}.
  73      * </ul>
  74      *
  75      * @param serviceType
  76      *            - Subclass of RpcService for which Router is to be generated.
  77      * @return Instance of RpcService of provided serviceType which implements
  78      *         also {@link RpcRouter}<T> and {@link DelegateProxy}
  79      */
  80     <T extends RpcService> T getRouterFor(Class<T> serviceType) throws IllegalArgumentException;
  81 }