X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=yang%2Fyang-model-util%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fyangtools%2Fyang%2Fmodel%2Futil%2Frepo%2FAbstractCachingSchemaSourceProvider.java;h=5b084e3fb1056e5fd68d30b6bb02cdb3b7f4766f;hb=refs%2Fchanges%2F77%2F14377%2F2;hp=f3f2c2ca0ad384f3e10b0e8f6a4c7e02449de68d;hpb=6f5a05159fb2c12717e3d5465b1963e475b320c8;p=yangtools.git

diff --git a/yang/yang-model-util/src/main/java/org/opendaylight/yangtools/yang/model/util/repo/AbstractCachingSchemaSourceProvider.java b/yang/yang-model-util/src/main/java/org/opendaylight/yangtools/yang/model/util/repo/AbstractCachingSchemaSourceProvider.java
index f3f2c2ca0a..5b084e3fb1 100644
--- a/yang/yang-model-util/src/main/java/org/opendaylight/yangtools/yang/model/util/repo/AbstractCachingSchemaSourceProvider.java
+++ b/yang/yang-model-util/src/main/java/org/opendaylight/yangtools/yang/model/util/repo/AbstractCachingSchemaSourceProvider.java
@@ -7,47 +7,71 @@
  */
 package org.opendaylight.yangtools.yang.model.util.repo;
 
-import org.opendaylight.yangtools.concepts.Delegator;
-import org.opendaylight.yangtools.concepts.Registration;
-
+import com.google.common.annotations.Beta;
 import com.google.common.base.Optional;
+import com.google.common.base.Preconditions;
+import org.opendaylight.yangtools.concepts.Delegator;
 
-import static com.google.common.base.Preconditions.*;
 
+/**
+ *
+ * Abstract caching schema provider with support of multiple context
+ * per backing {@link SchemaSourceProvider}.
+ *
+ * @param <I> Input Schema Source Representation
+ * @param <O> Output Schema Source Representation
+ *
+ * @deprecated Replaced with {@link org.opendaylight.yangtools.yang.model.repo.util.AbstractSchemaSourceCache}
+ */
+@Deprecated
 public abstract class AbstractCachingSchemaSourceProvider<I, O> implements AdvancedSchemaSourceProvider<O>,
         Delegator<AdvancedSchemaSourceProvider<I>> {
 
-    public class CompatibilitySchemaSourceProviderInstance implements SchemaSourceProvider<O> {
-
-        @Override
-        public Optional<O> getSchemaSource(String moduleName, Optional<String> revision) {
-            // TODO Auto-generated method stub
-            return null;
-        }
-
-    }
-
     private final AdvancedSchemaSourceProvider<I> defaultDelegate;
 
-    protected AbstractCachingSchemaSourceProvider(AdvancedSchemaSourceProvider<I> delegate) {
+    /**
+     * Construct caching schema source provider with supplied delegate.
+     *
+     * Default delegate is is used to retrieve schema source when cache does not
+     * contain requested sources.
+     *
+     * @param delegate SchemaSourceProvided used to look up and retrieve schema source
+     * when cache does not contain requested sources.
+     */
+    protected AbstractCachingSchemaSourceProvider(final AdvancedSchemaSourceProvider<I> delegate) {
         this.defaultDelegate = delegate;
     }
 
     @Override
-    public Optional<O> getSchemaSource(String moduleName, Optional<String> revision) {
-        checkNotNull(moduleName, "Module name should not be null.");
-        checkNotNull(revision, "Revision should not be null");
+    public Optional<O> getSchemaSource(final String moduleName, final Optional<String> revision) {
+        Preconditions.checkNotNull(moduleName, "Module name should not be null.");
+        Preconditions.checkNotNull(revision, "Revision should not be null");
         return getSchemaSource(SourceIdentifier.create(moduleName, revision));
     }
-    
+
     @Override
-    public Optional<O> getSchemaSource(SourceIdentifier sourceIdentifier) {
+    public Optional<O> getSchemaSource(final SourceIdentifier sourceIdentifier) {
         return getSchemaSourceImpl(sourceIdentifier, defaultDelegate);
     }
 
-    protected final Optional<O> getSchemaSourceImpl(SourceIdentifier identifier,
-            AdvancedSchemaSourceProvider<I> delegate) {
-        checkNotNull(identifier, "Source identifier name should not be null.");
+    /**
+     * Actual implementation of schema source retrieval.
+     *
+     * <ul>
+     * <li>look up cached schema source via {@link #getCachedSchemaSource(SourceIdentifier)}
+     * <li>If source was found in cache, returns source to client code.
+     * <li>If source was not found in cache, Look up schema source in supplied <code>delegate</code>
+     * <li>Updates cache with schema from delegate by {@link #cacheSchemaSource(SourceIdentifier, Optional)}
+     * <li>Result is returned to client code.
+     * </ul>
+     *
+     * @param identifier Source identifier
+     * @param delegate Delegate to lookup if there is a miss.
+     * @return Optional of schema source, present if source was found. Absent otherwise.
+     */
+    protected final Optional<O> getSchemaSourceImpl(final SourceIdentifier identifier,
+            final AdvancedSchemaSourceProvider<I> delegate) {
+        Preconditions.checkNotNull(identifier, "Source identifier name should not be null.");
 
         Optional<O> cached = getCachedSchemaSource(identifier);
         if (cached.isPresent()) {
@@ -57,33 +81,81 @@ public abstract class AbstractCachingSchemaSourceProvider<I, O> implements Advan
         return cacheSchemaSource(identifier, live);
     }
 
-    abstract protected Optional<O> cacheSchemaSource(SourceIdentifier identifier, Optional<I> stream);
-
+    /**
+     * Caches supplied result and returns cached result which should be returned to client.
+     *
+     * <p>
+     * Implementations of cache are required to cache schema source if possible.
+     * They are not required to cache {@link Optional#absent()}.
+     *
+     * Implementations are required to transform source representation if <code>O</code> and <code>I</code>
+     * are different.
+     *
+     * This method SHOULD NOT fail and should recover from Runtime exceptions
+     * by not caching source and only transforming it.
+     *
+     * @param identifier Source Identifier for which schema SHOULD be cached
+     * @param input Optional of schema source, representing one returned from delegate.
+     * @return Optional of schema source, representing result returned from this cache.
+     */
+    abstract protected Optional<O> cacheSchemaSource(SourceIdentifier identifier, Optional<I> input);
+
+    /**
+     * Returns cached schema source of {@link Optional#absent()} if source is not present in cache.
+     *
+     * <p>
+     * Implementations of cache MUST return cached schema source, if it is present in cache,
+     * otherwise source will be requested from deleate and then cache will be updated
+     * via {@link #cacheSchemaSource(SourceIdentifier, Optional)}.
+     *
+     * @param identifier Source Identifier for which schema should be retrieved.
+     * @return Cached schema source.
+     */
     abstract protected Optional<O> getCachedSchemaSource(SourceIdentifier identifier);
 
+    @Override
     public AdvancedSchemaSourceProvider<I> getDelegate() {
         return defaultDelegate;
     }
 
-    public SchemaSourceProvider<O> createInstanceFor(SchemaSourceProvider<I> delegate) {
-        checkNotNull(delegate, "Delegate should not be null");
+    /**
+     * Creates an lightweight instance of source provider, which uses this cache for caching
+     * and supplied additional delegate for lookup of not cached sources.
+     * <p>
+     *
+     * @param delegate Backing {@link SchemaSourceProvider} which should be used for lookup
+     *   for sources not present in schema.
+     * @return new instance of {@link SchemaSourceProvider} which first lookup in cache
+     *   and then in delegate.
+     *
+     */
+    @Beta
+    public SchemaSourceProvider<O> createInstanceFor(final SchemaSourceProvider<I> delegate) {
         return new SchemaSourceProviderInstance(SchemaSourceProviders.toAdvancedSchemaSourceProvider(delegate));
-            
+
     }
 
+    /**
+     *
+     * Lightweight instance of source provider, which is associated with parent
+     * {@link AbstractCachingSchemaSourceProvider}, but uses
+     * different delegate for retrieving not cached sources.
+     *
+     */
+    @Beta
     private class SchemaSourceProviderInstance implements //
-    AdvancedSchemaSourceProvider<O>, 
+    AdvancedSchemaSourceProvider<O>,
     Delegator<AdvancedSchemaSourceProvider<I>> {
 
         private final AdvancedSchemaSourceProvider<I> delegate;
 
-        protected SchemaSourceProviderInstance(AdvancedSchemaSourceProvider<I> delegate) {
+        protected SchemaSourceProviderInstance(final AdvancedSchemaSourceProvider<I> delegate) {
             super();
-            this.delegate = delegate;
+            this.delegate = Preconditions.checkNotNull(delegate, "Delegate should not be null");;
         }
 
         @Override
-        public Optional<O> getSchemaSource(String moduleName, Optional<String> revision) {
+        public Optional<O> getSchemaSource(final String moduleName, final Optional<String> revision) {
             return getSchemaSource(SourceIdentifier.create(moduleName, revision));
         }
 
@@ -93,7 +165,7 @@ public abstract class AbstractCachingSchemaSourceProvider<I, O> implements Advan
         }
 
         @Override
-        public Optional<O> getSchemaSource(SourceIdentifier sourceIdentifier) {
+        public Optional<O> getSchemaSource(final SourceIdentifier sourceIdentifier) {
             return getSchemaSourceImpl(sourceIdentifier, getDelegate());
         }
     }