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.util.Iterator;
22
23 /**
24 * A resource collection is a set of {@link PlexusIoResource} instances.
25 */
26 public interface PlexusIoResourceCollection extends Iterable<PlexusIoResource> {
27 /**
28 * Returns an iterator over the resources in the collection.
29 * @return An iterator
30 * @throws java.io.IOException .
31 */
32 Iterator<PlexusIoResource> getResources() throws IOException;
33
34 /**
35 * Returns the resources as a stream.
36 * @return A stream for functional iteration
37 */
38 Stream stream();
39
40 /**
41 * Returns the resources suggested name. This is used for
42 * integrating file mappers.
43 * @param resource A resource, which has been obtained by
44 * calling {@link #getResources()}.
45 * @return The resource name. If it is a file, it should be normalized to platform separators
46 */
47 String getName(PlexusIoResource resource);
48
49 /**
50 * Returns the collections last modification time. For a
51 * collection of files, this might be the last modification
52 * time of the file, which has been modified at last. For an
53 * archive file, this might be the modification time of the
54 * archive file.
55 * @return {@link PlexusIoResource#UNKNOWN_MODIFICATION_DATE},
56 * if the collections last modification time is unknown,
57 * otherwise the last modification time in milliseconds.
58 * @throws java.io.IOException .
59 */
60 long getLastModified() throws IOException;
61
62 /**
63 * Returns an input stream for the provided resource, with stream transformers applied
64 * @param resource The resources
65 * @return A possibly transformed resource
66 * @throws IOException when something goes bad
67 */
68 InputStream getInputStream(PlexusIoResource resource) throws IOException;
69
70 /**
71 * Resolves the supplied resource into a "real" resource. Resolving
72 * means applying input transformations
73 * Returns an input stream for the provided resource, with stream transformers applied
74 * @param resource The resources
75 * @return A possibly transformed resource
76 * @throws IOException when something goes bad
77 */
78 PlexusIoResource resolve(PlexusIoResource resource) throws IOException;
79
80 /**
81 * Indicates if this collection supports concurrent access to its resources.
82 * <p>Some resource collections (like tar files) may not support efficient random access
83 * or seek operation so implementations that represent such collections may not be able
84 * to provide concurrent access to its resources. If implementation returns {@code false},
85 * then it is not safe to access its methods and resources in concurrent fashion.
86 * For example it is not safe to read from two resources in two concurrent threads,
87 * to read a resource and iterate over the iterator returned by {@link #getResources()}
88 * in two concurrent threads, etc.
89 * <p>Please note that this method indicates concurrent support only for the collection,
90 * not for the individual resources. This means there is no guarantee that
91 * the resources returned by {@link #resolve(PlexusIoResource)} or the input stream
92 * returned by {@link #getInputStream(PlexusIoResource)} are thread-safe,
93 * even if {@code true} is returned.
94 * @return {@code true} if this collection supports concurrent access,
95 * otherwise {@code false}
96 */
97 boolean isConcurrentAccessSupported();
98 }