1/*
2 * Copyright (C) 2010 Google Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.google.clearsilver.jsilver.resourceloader;
18
19import com.google.clearsilver.jsilver.exceptions.JSilverTemplateNotFoundException;
20
21import java.io.IOException;
22import java.io.Reader;
23
24/**
25 * Loads resources, from somewhere.
26 *
27 * This is a service provider interface (SPI) for JSilver. Users of JSilver can easily create their
28 * own implementations. However, it is recommended that new implementations don't implement this
29 * interface directly, but instead extends {@link BaseResourceLoader}. This allows API changes to be
30 * made to JSilver that maintain compatibility with existing ResourceLoader implementations.
31 *
32 * @see BaseResourceLoader
33 * @see InMemoryResourceLoader
34 * @see FileSystemResourceLoader
35 * @see ClassLoaderResourceLoader
36 * @see ClassResourceLoader
37 */
38public interface ResourceLoader {
39
40  /**
41   * Open a resource. If this resource is not found, null should be returned.
42   *
43   * The caller of this method is guaranteed to call {@link #close(Reader)} when done with the
44   * reader.
45   *
46   * @param name the name of the resource
47   * @return Reader, or null if not found.
48   * @throws IOException if resource fails to open
49   */
50  Reader open(String name) throws IOException;
51
52  /**
53   * Open a resource or throw an exception if no such resource is found.
54   *
55   * The caller of this method is guaranteed to call {@link #close(Reader)} when done with the
56   * reader.
57   *
58   * @param name the name of the resource
59   * @return Reader, or null if not found.
60   * @throws JSilverTemplateNotFoundException if resource is not found
61   * @throws IOException if resource fails to open
62   */
63  Reader openOrFail(String name) throws JSilverTemplateNotFoundException, IOException;
64
65  /**
66   * Close the reader. Allows ResourceLoader to perform any additional clean up.
67   *
68   * @param reader the reader to close
69   * @throws IOException if reader fasils to close
70   */
71  void close(Reader reader) throws IOException;
72
73  /**
74   * Returns an object that can be used to uniquely identify the file corresponding to the given
75   * file name in the context of this ResourceLoader. (e.g. ordered list of directories + filename,
76   * or absolute file path.).
77   *
78   * @param filename the name we want to identify
79   * @return unique identifier
80   */
81  Object getKey(String filename);
82
83  /**
84   * Returns an object that can be used to identify when a resource has changed. This key should be
85   * based on some piece(s) of metadata that strongly indicates the resource has changed, for
86   * example a file's last modified time. Since the object is expected to be used as part of a cache
87   * key, it should be immutable and implement {@link Object#equals(Object)} and
88   * {@link Object#hashCode()} .
89   *
90   * If the ResourceLoader does not or cannot compute a version identifier then it is sufficient to
91   * always return the same Object, e.g. the resource name. Null, however, should only be returned
92   * if a call to {@link #open(String)} would also return null.
93   *
94   * @param name the name of the resource to check for resources
95   * @return unique identifier for the current version of the resource or null if the resource
96   *         cannot be found
97   */
98  Object getResourceVersionId(String name);
99}
100