yang/yang-model-api/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.repo.api.MissingSchemaSourceException;
  14 import org.opendaylight.yangtools.yang.model.repo.api.SchemaSourceRepresentation;
  15 import org.opendaylight.yangtools.yang.model.repo.api.SourceIdentifier;
  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 SchemaSourceRepresentation> {
  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
  32      * a representation of that particular revision or throw {@link MissingSchemaSourceException}.
  33      * <li> If the source identifier does not specify a revision, this method returns
  34      * the newest available revision, or throws {@link MissingSchemaSourceException}.
  35      * </ul>
  36      *
  37      * <p>
  38      * In either case the returned representation is required to report a non-null
  39      * revision in the {@link SourceIdentifier} returned from
  40      * {@link SchemaSourceRepresentation#getIdentifier()}.
  41      *
  42      * <p>
  43      * Implementations are not required to provide constant behavior in time, notably
  44      * this different invocation of this method may produce different results.
  45      *
  46      * @param sourceIdentifier source identifier
  47      * @return future source representation, if supplied YANG module is available
  48      * @throws NullPointerException if {@code sourceIdentifier} is null
  49      */
  50     @NonNull ListenableFuture<? extends T> getSource(@NonNull SourceIdentifier sourceIdentifier);
  51 }