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  /***
25   * Base interface for resolving a source by system identifiers.
26   * Instead of using the java.net.URL classes which prevent you
27   * from adding your own custom protocols in a server environment,
28   * you should use this resolver for all URLs.
29   *
30   * The resolver creates for each source a <code>Source</code>
31   * object, which could then be asked for an <code>InputStream</code>
32   * etc.
33   *
34   * When the <code>Source</code> object is no longer needed
35   * it must be released using the resolver. This is very similar like
36   * looking up components from a <code>ComponentLocator</code>.
37   * In fact a source object can implement most lifecycle interfaces
38   * like Composable, Initializable, Disposable etc.
39   *
40   * @author <a href="mailto:dev@avalon.apache.org">Avalon Development Team</a>
41   * @version CVS $Revision: 1.7 $ $Date: 2004/02/28 11:47:26 $
42   */
43  
44  public interface SourceResolver {
45  
46      /*** With this parameter you can specify the method to use for getting
47       * the content. It is up to the protocol implementation ({@link
48       * SourceFactory}) to support this or not
49       */
50      String METHOD = Source.class.getName()+".uri.method";
51  
52      /*** With this parameter you can specify additional request parameters which are
53       *  appended  to the URI. It is up to the protocol implementation ({@link
54       * SourceFactory}) to support this or not.
55       */
56      String URI_PARAMETERS = Source.class.getName()+".uri.parameters";
57  
58      /*** With this parameter you can specify the encoding to use for encoding
59       * the additional request parameters the URI. It is up to the protocol
60       * implementation ({@link SourceFactory}) to support this or not.
61       */
62      String URI_ENCODING = Source.class.getName()+".uri.encoding";
63  
64      void setMethod(String m);
65      
66      void setUriParameters(Map params);
67      
68      void setUriEncoding(String enc);
69          
70  	
71      /***
72       * Get a {@link Source} object. This is a shortcut for {@link #resolveURI
73       * (String, String, Map)}.
74       * 
75       * @return the resolved source object.
76       * @throws MalformedURLException if <code>location</code> is malformed.
77       * @throws IOException if the source couldn't be created for some other reason.
78       */
79      Source resolveURI( String location )
80          throws MalformedURLException, IOException;
81  
82      /***
83       * Get a {@link Source} object.
84       * @param location - the URI to resolve. If this is relative it is either
85       *                   resolved relative to the base parameter (if not null)
86       *                   or relative to a base setting of the source resolver
87       *                   itself.
88       * @param base - a base URI for resolving relative locations. This
89       *               is optional and can be <code>null</code>.
90       * @param parameters - Additional parameters for the URI. The parameters
91       *                     are specific to the used scheme.
92       * @return the resolved source object.
93       * @throws MalformedURLException if <code>location</code> is malformed.
94       * @throws IOException if the source couldn't be created for some other reason.
95       */
96      Source resolveURI( String location,
97                         String base,
98                         Map parameters )
99          throws MalformedURLException, IOException;
100 
101     /***
102      * Releases a resolved resource.
103      * 
104      * @param source the source to release.
105      */
106     void release( Source source );
107 }