/*
 * Copyright (C) 2010 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.clearsilver.jsilver.resourceloader;

import com.google.clearsilver.jsilver.exceptions.JSilverTemplateNotFoundException;

import java.io.IOException;
import java.io.Reader;

/**
 * Loads resources, from somewhere.
 * 
 * This is a service provider interface (SPI) for JSilver. Users of JSilver can easily create their
 * own implementations. However, it is recommended that new implementations don't implement this
 * interface directly, but instead extends {@link BaseResourceLoader}. This allows API changes to be
 * made to JSilver that maintain compatibility with existing ResourceLoader implementations.
 * 
 * @see BaseResourceLoader
 * @see InMemoryResourceLoader
 * @see FileSystemResourceLoader
 * @see ClassLoaderResourceLoader
 * @see ClassResourceLoader
 */
public interface ResourceLoader {

  /**
   * Open a resource. If this resource is not found, null should be returned.
   * 
   * The caller of this method is guaranteed to call {@link #close(Reader)} when done with the
   * reader.
   * 
   * @param name the name of the resource
   * @return Reader, or null if not found.
   * @throws IOException if resource fails to open
   */
  Reader open(String name) throws IOException;

  /**
   * Open a resource or throw an exception if no such resource is found.
   * 
   * The caller of this method is guaranteed to call {@link #close(Reader)} when done with the
   * reader.
   * 
   * @param name the name of the resource
   * @return Reader, or null if not found.
   * @throws JSilverTemplateNotFoundException if resource is not found
   * @throws IOException if resource fails to open
   */
  Reader openOrFail(String name) throws JSilverTemplateNotFoundException, IOException;

  /**
   * Close the reader. Allows ResourceLoader to perform any additional clean up.
   * 
   * @param reader the reader to close
   * @throws IOException if reader fasils to close
   */
  void close(Reader reader) throws IOException;

  /**
   * Returns an object that can be used to uniquely identify the file corresponding to the given
   * file name in the context of this ResourceLoader. (e.g. ordered list of directories + filename,
   * or absolute file path.).
   * 
   * @param filename the name we want to identify
   * @return unique identifier
   */
  Object getKey(String filename);

  /**
   * Returns an object that can be used to identify when a resource has changed. This key should be
   * based on some piece(s) of metadata that strongly indicates the resource has changed, for
   * example a file's last modified time. Since the object is expected to be used as part of a cache
   * key, it should be immutable and implement {@link Object#equals(Object)} and
   * {@link Object#hashCode()} .
   * 
   * If the ResourceLoader does not or cannot compute a version identifier then it is sufficient to
   * always return the same Object, e.g. the resource name. Null, however, should only be returned
   * if a call to {@link #open(String)} would also return null.
   * 
   * @param name the name of the resource to check for resources
   * @return unique identifier for the current version of the resource or null if the resource
   *         cannot be found
   */
  Object getResourceVersionId(String name);
}