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