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 javax.annotation.Nonnull;
20
21 import java.io.IOException;
22 import java.io.InputStream;
23 import java.net.URL;
24
25 import org.codehaus.plexus.components.io.fileselectors.FileInfo;
26 import org.codehaus.plexus.components.io.functions.ContentSupplier;
27 import org.codehaus.plexus.components.io.functions.SizeSupplier;
28
29 /**
30 * A resource is a file-like entity. It may be an actual file,
31 * an URL, a zip entry, or something like that.
32 */
33 public interface PlexusIoResource extends FileInfo, SizeSupplier, ContentSupplier {
34 /**
35 * Unknown resource size.
36 */
37 long UNKNOWN_RESOURCE_SIZE = -1;
38
39 /**
40 * Unknown modification date
41 */
42 long UNKNOWN_MODIFICATION_DATE = 0;
43
44 /**
45 * Returns the date, when the resource was last modified, if known.
46 * Otherwise, returns {@link #UNKNOWN_MODIFICATION_DATE}.
47 * @see java.io.File#lastModified()
48 */
49 long getLastModified();
50
51 /**
52 * Returns, whether the resource exists.
53 */
54 boolean isExisting();
55
56 /**
57 * Returns the resources size, if known. Otherwise returns
58 * {@link #UNKNOWN_RESOURCE_SIZE}.
59 */
60 long getSize();
61
62 /**
63 * Returns, whether the {@link FileInfo} refers to a file.
64 */
65 boolean isFile();
66
67 /**
68 * Returns, whether the {@link FileInfo} refers to a directory.
69 */
70 boolean isDirectory();
71
72 /**
73 * Creates an {@link java.io.InputStream}, which may be used to read
74 * the files contents. This is useful, if the file selector
75 * comes to a decision based on the files contents.
76 * <p>
77 * Please note that this InputStream is unbuffered. Clients should wrap this in a
78 * BufferedInputStream or attempt reading reasonably large chunks (8K+).
79 */
80 @Nonnull
81 InputStream getContents() throws IOException;
82
83 /**
84 * Returns an {@link URL}, which may be used to reference the
85 * resource, if possible.
86 * @return An URL referencing the resource, if possible, or null.
87 * In the latter case, you are forced to use {@link #getContents()}.
88 */
89 URL getURL() throws IOException;
90 }