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