View Javadoc

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