View Javadoc
1   package org.codehaus.plexus.resource;
2   
3   /*
4    * The MIT License
5    *
6    * Copyright (c) 2004, The Codehaus
7    *
8    * Permission is hereby granted, free of charge, to any person obtaining a copy of
9    * this software and associated documentation files (the "Software"), to deal in
10   * the Software without restriction, including without limitation the rights to
11   * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
12   * of the Software, and to permit persons to whom the Software is furnished to do
13   * so, subject to the following conditions:
14   *
15   * The above copyright notice and this permission notice shall be included in all
16   * copies or substantial portions of the Software.
17   *
18   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19   * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20   * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21   * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22   * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23   * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24   * SOFTWARE.
25   */
26  
27  import java.io.File;
28  import java.io.IOException;
29  import java.io.InputStream;
30  import java.net.URI;
31  import java.net.URL;
32  
33  /**
34   * A resource is a byte stream, possibly (but not necessarily) with additional attributes like {@link File}, {@link URL}
35   * , or {@link URI}.
36   * 
37   * @since 1.0-alpha-5
38   */
39  public interface PlexusResource
40  {
41      /**
42       * <p>
43       * Returns the resource as an {@link InputStream}. In general, you should not assume, that this method may me called
44       * more than once. In typical cases (for example, if the Resource is backed by a file or loaded through the
45       * classpath), one may create an {@link InputStream} as often as is necessary. However, you should think of cases
46       * like an URL pointing to a servlet, where the resource contents change with every call.
47       * </p>
48       * <p>
49       * If you need a reliable way of reloading the resource more than once, then you should use
50       * {@link ResourceManager#getResourceAsFile(PlexusResource)}.
51       * </p>
52       * 
53       * @return An {@link InputStream} with the resources contents, never null.
54       */
55      public InputStream getInputStream()
56          throws IOException;
57  
58      /**
59       * <p>
60       * Returns the resource as a file, if possible. A resource doesn't need to be available as a file: If you require a
61       * file, use {@link ResourceManager#getResourceAsFile(PlexusResource)}.
62       * </p>
63       * 
64       * @return A {@link File} containing the resources contents, if available, or null.
65       */
66      public File getFile()
67          throws IOException;
68  
69      /**
70       * <p>
71       * Returns the resources URL, if possible. A resource doesn't need to have an URL.
72       * </p>
73       * 
74       * @return The resources URL, if available, or null.
75       */
76      public URL getURL()
77          throws IOException;
78  
79      /**
80       * <p>
81       * Returns the resources URI, if possible. A resource doesn't need to have an URI.
82       * </p>
83       * 
84       * @return The resources URI, if available, or null.
85       */
86      public URI getURI()
87          throws IOException;
88  
89      /**
90       * Returns the resources name, if possible. A resources name is a relatively unspecified thing. For example, if the
91       * resource has an {@link URL}, the name might be created by invoking {@link URL#toExternalForm()}. In the case of a
92       * {@link File}, it might be {@link File#getPath()}.
93       */
94      public String getName();
95  }