001: /*
002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
003: * Distributed under the terms of either:
004: * - the common development and distribution license (CDDL), v1.0; or
005: * - the GNU Lesser General Public License, v2.1 or later
006: * $Id: ResourceFinder.java 3634 2007-01-08 21:42:24Z gbevin $
007: */
008: package com.uwyn.rife.resources;
009:
010: import com.uwyn.rife.resources.exceptions.ResourceFinderErrorException;
011: import com.uwyn.rife.tools.InnerClassException;
012: import com.uwyn.rife.tools.InputStreamUser;
013: import java.net.URL;
014:
015: /**
016: * This interface defines the methods that classes with
017: * <code>ResourceFinder</code> functionalities have to implement.
018: * <p>
019: * A <code>ResourceFinder</code> provides an abstract way of working
020: * with resources. According to a name, a resource can be searched for and its
021: * location is returned as an <code>URL</code> object.
022: * <p>
023: * It also possible to obtain a stream to read the resource's content,
024: * to retrieve all its contents as a <code>String</code> and to obtain the
025: * modification time of the resource.
026: *
027: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
028: * @version $Revision: 3634 $
029: * @see com.uwyn.rife.resources.ResourceWriter
030: * @since 1.0
031: */
032: public interface ResourceFinder {
033: /**
034: * Retrieves the resource that corresponds to the provided name.
035: * <p>
036: * This method never throws an exception, but returns <code>null</code> in
037: * case of an exception.
038: *
039: * @param name the name of the resource to retrieve
040: *
041: * @return the <code>URL</code> object that corresponds to the provided
042: * name; or
043: * <p>
044: * <code>null</code> if the resource couldn't be found or if an error
045: * occurred.
046: *
047: * @since 1.0
048: */
049: public URL getResource(String name);
050:
051: /**
052: * Returns a stream that can be used to read the contents of the resource
053: * that corresponds to the provided name.
054: *
055: * @param name the name of the resource to retrieve
056: * @param user an instance of <code>InputStreamUser</code>
057: * that contains the logic that will be executed with this stream
058: * @return the return value from the <code>useInputStream</code> method of
059: * the provided <code>InputStreamUser</code> instance
060: *
061: * @exception ResourceFinderErrorException when an error occurred during the
062: * creation or opening of the stream.
063: * @exception InnerClassException when errors occurs inside the
064: * <code>InputStreamUser</code>
065: *
066: * @see InputStreamUser
067: * @see #useStream(URL, InputStreamUser)
068: *
069: * @since 1.0
070: */
071: public <ResultType> ResultType useStream(String name,
072: InputStreamUser user) throws ResourceFinderErrorException,
073: InnerClassException;
074:
075: /**
076: * Returns a stream that can be used to read the contents of the provided
077: * resource.
078: *
079: * @param resource the resource to retrieve
080: * @param user an instance of <code>InputStreamUser</code>
081: * that contains the logic that will be executed with this stream
082: * @return the return value from the <code>useInputStream</code> method of
083: * the provided <code>InputStreamUser</code> instance
084: *
085: * @exception ResourceFinderErrorException when an error occurred during the
086: * creation or opening of the stream.
087: * @exception InnerClassException when errors occurs inside the
088: * <code>InputStreamUser</code>
089: *
090: * @see InputStreamUser
091: * @see #useStream(String, InputStreamUser)
092: *
093: * @since 1.0
094: */
095: public <ResultType> ResultType useStream(URL resource,
096: InputStreamUser user) throws ResourceFinderErrorException,
097: InnerClassException;
098:
099: /**
100: * Retrieves the complete content of the resource that corresponds to the
101: * provided name. The content will be read into a string by using the
102: * platform's default encoding.
103: *
104: * @param name the name of the resource to retrieve
105: *
106: * @return a <code>String</code> object that contains the complete content
107: * of the resource with the provided name; or
108: * <p>
109: * <code>null</code> if the resource couldn't be found.
110: *
111: * @throws ResourceFinderErrorException when an error occurred during the
112: * retrieval of the content.
113: *
114: * @see #getContent(String, String)
115: * @see #getContent(URL, String)
116: *
117: * @since 1.0
118: */
119: public String getContent(String name)
120: throws ResourceFinderErrorException;
121:
122: /**
123: * Retrieves the complete content of the resource that corresponds to the
124: * provided name.
125: *
126: * @param name the name of the resource to retrieve the content from
127: * @param encoding the encoding that should be used to read the content
128: *
129: * @return a <code>String</code> object that contains the complete content
130: * of the resource with the provided name; or
131: * <p>
132: * <code>null</code> if the resource couldn't be found.
133: *
134: * @throws ResourceFinderErrorException when an error occurred during the
135: * retrieval of the content or when the encoding is not supported.
136: *
137: * @see #getContent(String)
138: * @see #getContent(URL)
139: * @see #getContent(URL, String)
140: *
141: * @since 1.0
142: */
143: public String getContent(String name, String encoding)
144: throws ResourceFinderErrorException;
145:
146: /**
147: * Retrieves the complete content of the provided resource. The content will
148: * be read into a string by using the platform's default encoding.
149: *
150: * @param resource the resource to retrieve the content from
151: *
152: * @return a <code>String</code> object that contains the complete content
153: * of the resource with the provided name; or
154: * <p>
155: * <code>null</code> if the resource couldn't be found.
156: *
157: * @throws ResourceFinderErrorException when an error occurred during the
158: * retrieval of the content or when the encoding is not supported.
159: *
160: * @see #getContent(String)
161: * @see #getContent(String, String)
162: * @see #getContent(URL, String)
163: *
164: * @since 1.0
165: */
166: public String getContent(URL resource)
167: throws ResourceFinderErrorException;
168:
169: /**
170: * Retrieves the complete content of the provided resource.
171: *
172: * @param resource the resource to retrieve the content from
173: * @param encoding the encoding that should be used to read the content
174: *
175: * @return a <code>String</code> object that contains the complete content
176: * of the resource with the provided name; or
177: * <p>
178: * <code>null</code> if the resource couldn't be found.
179: *
180: * @throws ResourceFinderErrorException when an error occurred during the
181: * retrieval of the content or when the encoding is not supported.
182: *
183: * @see #getContent(String)
184: * @see #getContent(String, String)
185: * @see #getContent(URL)
186: *
187: * @since 1.0
188: */
189: public String getContent(URL resource, String encoding)
190: throws ResourceFinderErrorException;
191:
192: /**
193: * Retrieves the modification time of the resource that corresponds to the
194: * provided name.
195: *
196: * @param name the name of the resource to retrieve
197: *
198: * @return a positive <code>long</code> with the modification time in
199: * milliseconds; or
200: * <p>
201: * <code>-1</code> if the resource couldn't be found.
202: *
203: * @throws ResourceFinderErrorException when an error occurred during the
204: * retrieval of the modification time.
205: *
206: * @see #getModificationTime(URL)
207: *
208: * @since 1.0
209: */
210: public long getModificationTime(String name)
211: throws ResourceFinderErrorException;
212:
213: /**
214: * Retrieves the modification time of the provided resource.
215: *
216: * @param resource the resource to retrieve the modification time from
217: *
218: * @return a positive <code>long</code> with the modification time in
219: * milliseconds; or
220: * <p>
221: * <code>-1</code> if the resource couldn't be found.
222: *
223: * @throws ResourceFinderErrorException when an error occurred during the
224: * retrieval of the modification time.
225: *
226: * @see #getModificationTime(String)
227: *
228: * @since 1.0
229: */
230: public long getModificationTime(URL resource)
231: throws ResourceFinderErrorException;
232: }
|