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.base.Optional;
  12 import com.google.common.util.concurrent.ListenableFuture;
  13
  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 report the identifier as absent
  33      * by returning {@link Optional#absent()}.
  34      * <li> If the source identifier does not specify a revision, this method returns
  35      * the newest available revision, or {@link Optional#absent()}.
  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      *         {@link Optional#absent()} otherwise.
  47      */
  48     ListenableFuture<Optional<T>> getSource(SourceIdentifier sourceIdentifier);
  49 }