View Javadoc
1   package org.codehaus.plexus.components.io.resources;
2   
3   /*
4    * Copyright 2007 The Codehaus Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * 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, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.io.IOException;
20  import java.io.InputStream;
21  import java.net.URL;
22  
23  import org.codehaus.plexus.components.io.fileselectors.FileInfo;
24  import org.codehaus.plexus.components.io.functions.ContentSupplier;
25  import org.codehaus.plexus.components.io.functions.SizeSupplier;
26  
27  import javax.annotation.Nonnull;
28  
29  
30  /**
31   * A resource is a file-like entity. It may be an actual file,
32   * an URL, a zip entry, or something like that.
33   */
34  public interface PlexusIoResource extends FileInfo, SizeSupplier, ContentSupplier
35  {
36      /**
37       * Unknown resource size.
38       */
39      public static final long UNKNOWN_RESOURCE_SIZE = -1;
40  
41      /**
42       * Unknown modification date
43       */
44      public static final long UNKNOWN_MODIFICATION_DATE = 0;
45  
46      /**
47       * Returns the date, when the resource was last modified, if known.
48       * Otherwise, returns {@link #UNKNOWN_MODIFICATION_DATE}.
49       * @see java.io.File#lastModified()
50       */
51      long getLastModified();
52  
53      /**
54       * Returns, whether the resource exists.
55       */
56      boolean isExisting();
57  
58      /**
59       * Returns the resources size, if known. Otherwise returns
60       * {@link #UNKNOWN_RESOURCE_SIZE}.
61       */
62      long getSize();
63  
64  
65      /**
66       * Returns, whether the {@link FileInfo} refers to a file.
67       */
68      boolean isFile();
69  
70      /**
71       * Returns, whether the {@link FileInfo} refers to a directory.
72       */
73      boolean isDirectory();
74  
75      /**
76       * Creates an {@link java.io.InputStream}, which may be used to read
77       * the files contents. This is useful, if the file selector
78       * comes to a decision based on the files contents.
79       *
80       * Please note that this InputStream is unbuffered. Clients should wrap this in a
81       * BufferedInputStream or attempt reading reasonably large chunks (8K+).
82       */
83      @Nonnull
84      InputStream getContents() throws IOException;
85  
86      /**
87       * Returns an {@link URL}, which may be used to reference the
88       * resource, if possible.
89       * @return An URL referencing the resource, if possible, or null.
90       *   In the latter case, you are forced to use {@link #getContents()}.
91       */
92      URL getURL() throws IOException;
93  }