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