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