Merge "Bug 1305: Review YangTools grammar"

[yangtools.git] / yang / yang-model-util / src / main / java / org / opendaylight / yangtools / yang / model / util / repo / AdvancedSchemaSourceProvider.java

diff --git a/yang/yang-model-util/src/main/java/org/opendaylight/yangtools/yang/model/util/repo/AdvancedSchemaSourceProvider.java b/yang/yang-model-util/src/main/java/org/opendaylight/yangtools/yang/model/util/repo/AdvancedSchemaSourceProvider.java
index 1c7ffa1da54889bb04077f73c52fc21bd118f7d0..afb70736e156793910baef1e665376313e12ab01 100644 (file)
--- a/yang/yang-model-util/src/main/java/org/opendaylight/yangtools/yang/model/util/repo/AdvancedSchemaSourceProvider.java
+++ b/yang/yang-model-util/src/main/java/org/opendaylight/yangtools/yang/model/util/repo/AdvancedSchemaSourceProvider.java
@@ -9,7 +9,56 @@ package org.opendaylight.yangtools.yang.model.util.repo;
 
 import com.google.common.base.Optional;
 
-public interface AdvancedSchemaSourceProvider<F> extends SchemaSourceProvider<F> {
+/**
+ * Provider of representation of YANG schema sources.
+ *
+ * <p>
+ * {@link AdvancedSchemaSourceProvider} is extension of
+ * {@link SchemaSourceProvider} which did not have object concept of source
+ * identifier, and introduces {@link SourceIdentifier} (which contains schema
+ * name and revision) as identifier of sources.
+ *
+ * <p>
+ * <b>Schema Source representation</b>
+ * <p>
+ * Representation of schema source. Representation of schema source could exists
+ * in various formats (Java types), depending on stage of processing, but
+ * representation MUST BE still result of processing of only single unit of schema
+ * source (file, input stream). E.g.:
+ * <ul>
+ * <li>{@link java.lang.String} - textual representation of source code
+ * <li>{@link java.io.InputStream} - input stream containing source code
+ * <li>{@link com.google.common.io.ByteSource} - source for input streams
+ * containing source code
+ * <li>Parsed AST - abstract syntax tree, which is result of a parser, but still
+ * it is not linked against other schemas.
+ * </ul>
+ *
+ * <p>
+ * Conversion between representations should be done via implementations of
+ * {@link SchemaSourceTransformation}.
+ *
+ * @param <T>
+ *            Schema source representation type provided by this implementation
+ *
+ * @deprecated Replaced with {@link org.opendaylight.yangtools.yang.model.repo.spi.SchemaSourceProvider}
+ * and related APIs.
+ */
+@Deprecated
+public interface AdvancedSchemaSourceProvider<T> extends SchemaSourceProvider<T> {
 
-    Optional<F> getSchemaSource(SourceIdentifier sourceIdentifier);
+    /**
+     * Returns representation source for supplied YANG source identifier.
+     *
+     * Returned representation of schema source must be immutable, must not
+     * change during runtime if {@link SourceIdentifier} has specified both
+     * {@link SourceIdentifier#getName()} and
+     * {@link SourceIdentifier#getRevision()}
+     *
+     * @param sourceIdentifier
+     *            source identifier.
+     * @return source representation if supplied YANG module is available
+     *         {@link Optional#absent()} otherwise.
+     */
+    Optional<T> getSchemaSource(SourceIdentifier sourceIdentifier);
 }