KickJava   Java API By Example, From Geeks To Geeks.

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


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  * A source factory creates new source objects.
27  * <p>
28  * Source factories are used to extend the source resolving mechanism
29  * with new URI schemes. A new source factory is added in order to
30  * handle a specific prototol. The {@link SourceResolver} delegates
31  * the handling of a URI containing this new scheme to the factory,
32  * and the factory can create a corresponding {@link Source} object.
33  *
34  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
35  * @version $Id: SourceFactory.java,v 1.4 2004/02/28 11:47:26 cziegeler Exp $
36  */
37 public interface SourceFactory
38     extends Component
39 {
40     String JavaDoc ROLE = SourceFactory.class.getName();
41
42     /**
43      * Get a {@link Source} object.
44      * The factory creates a new {@link Source} object that can be used
45      * by the application. However, when this source object is not needed
46      * anymore it has to be released again using the {@link #release(Source)}
47      * method. This is achieved by using {@link SourceResolver#release(Source)} which
48      * finds the appropriate <code>SourceFactory</code>.
49      *
50      * @param location The URI to resolve - this URI includes the scheme.
51      * @param parameters additionnal named parameters (optionnal and can be <code>null</code>)
52      * that drive the creation of the <code>Source</code> object. Each implementation
53      * must specify what parameters it accepts.
54      * @return the created source object.
55      *
56      * @throws IOException if the source couldn't be created for some reason.
57      */
58     Source getSource( String JavaDoc location, Map JavaDoc parameters )
59         throws IOException JavaDoc, MalformedURLException JavaDoc;
60     
61     /**
62      * Release a {@link Source} object.
63      *
64      * @param source the source to release.
65      */
66     void release( Source source );
67 }
68
Popular Tags