opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcProviderService.java

   1 /*
   2  * Copyright (c) 2015 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.md.sal.dom.api;
   9
  10 import java.util.Set;
  11 import javax.annotation.Nonnull;
  12
  13 /**
  14  * A {@link DOMService} which allows registration of RPC implementations with a conceptual router. The client
  15  * counterpart of this service is {@link DOMRpcService}.
  16  *
  17  * <p>
  18  * This interface supports both RFC6020 RPCs and RFC7950 actions (formerly known as 'Routed RPCs'. Invocation for
  19  * RFC6020 RPCs is always based on an empty context reference. Invocation of actions requires a non-empty context
  20  * reference and is matched against registered implementations as follows:
  21  * <ul>
  22  *     <li>First, attempt to look up the implementation based on exact match. If a match is found the invocation is
  23  *         on that implementation, returning its result.</li>
  24  *     <li>Second, attempt to look up the implementation which registered for empty context reference. If a such an
  25  *         implementation exists, invoke that implementation, returning its result</li>
  26  *     <li>Throw {@link DOMRpcImplementationNotAvailableException}
  27  * </ul>
  28  *
  29  * <p>
  30  * All implementations are required to perform these steps as specified above.
  31  */
  32 public interface DOMRpcProviderService extends DOMService {
  33     /**
  34      * Register an {@link DOMRpcImplementation} object with this service.
  35      *
  36      * @param implementation RPC implementation, must not be null
  37      * @param rpcs Array of supported RPC identifiers. Must not be null, empty, or contain a null element.
  38      *             Each identifier is added exactly once, no matter how many times it occurs.
  39      * @return A {@link DOMRpcImplementationRegistration} object, guaranteed to be non-null.
  40      * @throws NullPointerException if implementation or types is null
  41      * @throws IllegalArgumentException if types is empty or contains a null element.
  42      */
  43     @Nonnull <T extends DOMRpcImplementation> DOMRpcImplementationRegistration<T> registerRpcImplementation(
  44             @Nonnull T implementation, @Nonnull DOMRpcIdentifier... rpcs);
  45
  46     /**
  47      * Register an {@link DOMRpcImplementation} object with this service.
  48      *
  49      * @param implementation RPC implementation, must not be null
  50      * @param rpcs Set of supported RPC identifiers. Must not be null, empty, or contain a null element.
  51      * @return A {@link DOMRpcImplementationRegistration} object, guaranteed to be non-null.
  52      * @throws NullPointerException if implementation or types is null
  53      * @throws IllegalArgumentException if types is empty or contains a null element.
  54      */
  55     @Nonnull <T extends DOMRpcImplementation> DOMRpcImplementationRegistration<T> registerRpcImplementation(
  56             @Nonnull T implementation, @Nonnull Set<DOMRpcIdentifier> rpcs);
  57 }