yang/yang-repo-spi/src/main/java/org/opendaylight/yangtools/yang/model/repo/spi/SchemaSourceProvider.java

   1 /*
   2  * Copyright (c) 2014 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.yangtools.yang.model.repo.spi;
   9
  10 import com.google.common.annotations.Beta;
  11 import com.google.common.util.concurrent.ListenableFuture;
  12 import org.eclipse.jdt.annotation.NonNull;
  13 import org.opendaylight.yangtools.yang.model.api.source.SourceIdentifier;
  14 import org.opendaylight.yangtools.yang.model.api.source.SourceRepresentation;
  15 import org.opendaylight.yangtools.yang.model.repo.api.MissingSchemaSourceException;
  16
  17 /**
  18  * Schema source provider implementations take care of resolving a {@link SourceIdentifier}
  19  * into a particular representation of the schema source. Examples of resolution include
  20  * fetching the source from an external source, opening a classpath resource, or similar.
  21  *
  22  * @param <T> Schema source representation type provided by this implementation
  23  */
  24 @Beta
  25 public interface SchemaSourceProvider<T extends SourceRepresentation> {
  26     /**
  27      * Returns a representation a for supplied YANG source identifier. The resolution
  28      * criteria are as follows:
  29      *
  30      * <ul>
  31      *   <li>If the source identifier specifies a revision, this method returns either a representation of that
  32      *       particular revision or throw {@link MissingSchemaSourceException}</li>
  33      *   <li>If the source identifier does not specify a revision, this method returns the newest available revision,
  34      *       or throws {@link MissingSchemaSourceException}</li>
  35      * </ul>
  36      *
  37      * <p>
  38      * In either case the returned representation is required to report a non-null revision in the
  39      * {@link SourceIdentifier} returned from {@link SourceRepresentation#sourceId()}.
  40      *
  41      * <p>
  42      * Implementations are not required to provide constant behavior in time, notably this different invocation of this
  43      * method may produce different results.
  44      *
  45      * @param sourceId source identifier
  46      * @return future source representation, if supplied YANG module is available
  47      * @throws NullPointerException if {@code sourceIdentifier} is null
  48      */
  49     @NonNull ListenableFuture<? extends T> getSource(@NonNull SourceIdentifier sourceId);
  50 }