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

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