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 17 package com.google.clearsilver.jsilver.resourceloader; 18 19 import com.google.clearsilver.jsilver.exceptions.JSilverTemplateNotFoundException; 20 21 import java.io.IOException; 22 import 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 */ 38 public 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
