01: /*
02: * ResourceEngine.java February 2001
03: *
04: * Copyright (C) 2001, Niall Gallagher <niallg@users.sf.net>
05: *
06: * This library is free software; you can redistribute it and/or
07: * modify it under the terms of the GNU Lesser General Public
08: * License as published by the Free Software Foundation.
09: *
10: * This library is distributed in the hope that it will be useful,
11: * but WITHOUT ANY WARRANTY; without even the implied warranty of
12: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13: * GNU Lesser General Public License for more details.
14: *
15: * You should have received a copy of the GNU Lesser General
16: * Public License along with this library; if not, write to the
17: * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18: * Boston, MA 02111-1307 USA
19: */
20:
21: package simple.http.serve;
22:
23: /**
24: * The <code>ResourceEngine</code> is used to create implementations
25: * of the <code>Resource</code> interface that suit the targeted
26: * resource. Different <code>Resource</code> objects may be needed to
27: * handle different files/directories or even applications. The request
28: * URI specified must be a HTTP request URI as of RFC 2616.
29: * <p>
30: * The meaning of HTTP URI in this instance is the request URI
31: * from a HTTP/x.x request, as RFC 2616 and RFC 2396 defines it
32: *
33: * <pre>
34: * Request-Line = Method SP Request-URI SP HTTP-Version CRLF
35: *
36: * Request-URI = "*" | absoluteURI | abs_path | authority
37: * absoluteURI = "http:" "//" host [":" port] [abs_path ["?" query]]
38: * abs_path = "/" path_segments
39: * path_segments = segment *( "/" segment )
40: * </pre>
41: *
42: * The <code>ResourceEngine</code> object must be prepared to accept
43: * the request URI that come in the form outlined above. These can
44: * include formats like
45: *
46: * <pre>
47: * http://some.host/pub;param=value/bin/index.html?name=value
48: * http://some.host:8080/index.en_US.html
49: * some.host:8080/index.html
50: * /usr/bin;param=value/README.txt
51: * /usr/bin/compress.tar.gz
52: * </pre>
53: *
54: * The <code>ResourceEngine</code> implementation should be able to
55: * directly take a Request-URI as defined in RFC 2616 and translate
56: * this into a <code>Resource</code>. This keeps the objects semantics
57: * simple and explicit, although at the expense of performance.
58: * <p>
59: * The <code>Resource</code> returned is an implementation of the
60: * <code>ProtocolHandler</code> interface. Implementation's of this
61: * can acquire the <code>Resource</code> based on the URI or query.
62: *
63: * @author Niall Gallagher
64: */
65: public interface ResourceEngine {
66:
67: /**
68: * This will look for and retrieve the requested resource. The
69: * target given must be in the form of a request URI. This will
70: * locate the resource and return the <code>Resource</code>
71: * implementation that will handle the target.
72: *
73: * @param target the URI style path that represents the target
74: * <code>Resource</code>
75: *
76: * @return this returns the <code>Resource</code> object to
77: * handle the desired target
78: *
79: * @throws IllegalArgumentException if the path given is not
80: * relative URI style
81: */
82: public Resource resolve(String target);
83: }
|