dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataTreeShardingService.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.mdsal.dom.api;
   9
  10 import javax.annotation.Nonnull;
  11 import org.opendaylight.yangtools.concepts.ListenerRegistration;
  12
  13 /**
  14  * A {@link DOMService} providing access to details on how the conceptual data tree
  15  * is distributed among providers (also known as shards). Each shard is tied to a
  16  * single {@link DOMDataTreeIdentifier}. Based on those data tree identifiers, the
  17  * shards are organized in a tree, where there is a logical parent/child relationship.
  18  *
  19  * <p>
  20  * It is not allowed to attach two shards to the same data tree identifier, which means
  21  * the mapping of each piece of information has an unambiguous home. When accessing
  22  * the information, the shard with the longest matching data tree identifier is used,
  23  * which is why this interface treats it is a prefix.
  24  *
  25  * <p>
  26  * Whenever a parent/child relationship is changed, the parent is notified, so it can
  27  * understand that a logical child has been attached.
  28  */
  29 public interface DOMDataTreeShardingService extends DOMService {
  30     /**
  31      * Register a shard as responsible for a particular subtree prefix.
  32      *
  33      * @param prefix Data tree identifier, may not be null.
  34      * @param shard Responsible shard instance
  35      * @param producer Producer instance to verify namespace claim
  36      * @return A registration. To remove the shard's binding, close the registration.
  37      * @throws DOMDataTreeShardingConflictException if the prefix is already bound
  38      */
  39     @Nonnull <T extends DOMDataTreeShard> ListenerRegistration<T> registerDataTreeShard(
  40             @Nonnull DOMDataTreeIdentifier prefix, @Nonnull T shard,
  41             @Nonnull DOMDataTreeProducer producer) throws DOMDataTreeShardingConflictException;
  42 }