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