View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.myfaces.trinidad.share.io;
20  
21  import java.io.InputStream;
22  import java.io.IOException;
23  
24  /**
25   * InputStreamProviders encapsulate a single target file. An InputStreamProvider is used to 
26   * get an inputStream, cache results and see if the file has been modified. 
27   * (There's no real requirement that there be a physical file
28   * at the target location).
29   * <p>
30   * @version $Name:  $ ($Revision: adfrt/faces/adf-faces-impl/src/main/java/oracle/adfinternal/view/faces/share/io/InputStreamProvider.java#0 $) $Date: 10-nov-2005.19:00:08 $
31   */
32  public interface InputStreamProvider
33  {
34    /**
35     * Return an InputStream for the target.  This function
36     * should never return null - if a stream cannot be opened,
37     * throw an IOException.
38     */
39    public InputStream       openInputStream() throws IOException;
40  
41    /**
42     * Returns the name of the target location, suitable
43     * for user display.
44     */
45    public String            getDisplayName();
46  
47    /**
48     * Returns an identifier object that uniquely
49     * identifies the target location. If two providers
50     * return equal identifiers, that is, given:
51     * <pre>
52     *   Object identifierA = providerA.getIdentifier();
53     *   Object identifierB = providerB.getIdentifier();
54     * </pre>
55     * ... then:
56     * <pre>
57     *   if (identifierA.equals(identifierB)) ...
58     * </pre>
59     * then the two providers must point to the same location.
60     */
61    public Object            getIdentifier();
62  
63    /**
64     * Returns true if the underlying target has changed
65     * since the last call to openInputStream()
66     */
67    public boolean           hasSourceChanged();
68  
69    /**
70     * Returns the cached result from reading and parsing this
71     * provider.
72     * @see CachingNameResolver
73     */
74    public Object            getCachedResult();
75  
76    /**
77     * Stores the cached result of reading and parsing this
78     * provider.
79     * @see CachingNameResolver
80     */
81    public void              setCachedResult(Object value);
82  }