KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > excalibur > source > SourceResolver


1 /*
2  * Copyright 2002-2004 The Apache Software Foundation
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
12  * implied.
13  *
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 package org.apache.excalibur.source;
18
19 import java.io.IOException JavaDoc;
20 import java.net.MalformedURLException JavaDoc;
21 import java.util.Map JavaDoc;
22
23 import org.apache.avalon.framework.component.Component;
24
25 /**
26  * Base interface for resolving a source by system identifiers.
27  * Instead of using the java.net.URL classes which prevent you
28  * from adding your own custom protocols in a server environment,
29  * you should use this resolver for all URLs.
30  *
31  * The resolver creates for each source a <code>Source</code>
32  * object, which could then be asked for an <code>InputStream</code>
33  * etc.
34  *
35  * When the <code>Source</code> object is no longer needed
36  * it must be released using the resolver. This is very similar like
37  * looking up components from a <code>ComponentLocator</code>.
38  * In fact a source object can implement most lifecycle interfaces
39  * like Composable, Initializable, Disposable etc.
40  *
41  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
42  * @version CVS $Revision: 1.7 $ $Date: 2004/02/28 11:47:26 $
43  */
44
45 public interface SourceResolver
46     extends Component
47 {
48     String JavaDoc ROLE = SourceResolver.class.getName();
49
50     /** With this parameter you can specify the method to use for getting
51      * the content. It is up to the protocol implementation ({@link
52      * SourceFactory}) to support this or not
53      */
54     String JavaDoc METHOD = Source.class.getName()+".uri.method";
55
56     /** With this parameter you can specify additional request parameters which are
57      * appended to the URI. It is up to the protocol implementation ({@link
58      * SourceFactory}) to support this or not.
59      */
60     String JavaDoc URI_PARAMETERS = Source.class.getName()+".uri.parameters";
61
62     /** With this parameter you can specify the encoding to use for encoding
63      * the additional request parameters the URI. It is up to the protocol
64      * implementation ({@link SourceFactory}) to support this or not.
65      */
66     String JavaDoc URI_ENCODING = Source.class.getName()+".uri.encoding";
67     
68     /**
69      * Get a {@link Source} object. This is a shortcut for {@link #resolveURI
70      * (String, String, Map)}.
71      *
72      * @return the resolved source object.
73      * @throws MalformetURLException if <code>location</code> is malformed.
74      * @throws IOException if the source couldn't be created for some other reason.
75      */
76     Source resolveURI( String JavaDoc location )
77         throws MalformedURLException JavaDoc, IOException JavaDoc;
78
79     /**
80      * Get a {@link Source} object.
81      * @param location - the URI to resolve. If this is relative it is either
82      * resolved relative to the base parameter (if not null)
83      * or relative to a base setting of the source resolver
84      * itself.
85      * @param base - a base URI for resolving relative locations. This
86      * is optional and can be <code>null</code>.
87      * @param parameters - Additional parameters for the URI. The parameters
88      * are specific to the used scheme.
89      * @return the resolved source object.
90      * @throws MalformetURLException if <code>location</code> is malformed.
91      * @throws IOException if the source couldn't be created for some other reason.
92      */
93     Source resolveURI( String JavaDoc location,
94                        String JavaDoc base,
95                        Map JavaDoc parameters )
96         throws MalformedURLException JavaDoc, IOException JavaDoc;
97
98     /**
99      * Releases a resolved resource.
100      *
101      * @param source the source to release.
102      */
103     void release( Source source );
104 }
105
Popular Tags