1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. 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,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.maven.api.services;
20
21 import java.io.IOException;
22 import java.io.InputStream;
23 import java.nio.file.Path;
24
25 import org.apache.maven.api.Session;
26 import org.apache.maven.api.annotations.Experimental;
27 import org.apache.maven.api.annotations.Nonnull;
28 import org.apache.maven.api.annotations.Nullable;
29
30 /**
31 * Provides access to the contents of a source independently of the
32 * backing store (e.g. file system, database, memory).
33 * <p>
34 * This is mainly used to parse files into objects such as
35 * {@link org.apache.maven.api.Project},
36 * {@link org.apache.maven.api.model.Model},
37 * {@link org.apache.maven.api.settings.Settings}, or
38 * {@link org.apache.maven.api.toolchain.PersistedToolchains}.
39 *
40 * @since 4.0.0
41 * @see org.apache.maven.api.services.ProjectBuilder#build(Session, Source)
42 * @see org.apache.maven.api.services.SettingsBuilder#build(Session, Source, Source, Source)
43 * @see org.apache.maven.api.services.ToolchainsBuilder#build(Session, Source, Source)
44 */
45 @Experimental
46 public interface Source {
47
48 /**
49 * Provides access the file to be parsed, if this source is backed by a file.
50 *
51 * @return the underlying {@code Path}, or {@code null} if this source is not backed by a file
52 */
53 @Nullable
54 Path getPath();
55
56 /**
57 * Creates a new byte stream to the source contents.
58 * Closing the returned stream is the responsibility of the caller.
59 *
60 * @return a byte stream to the source contents, never {@code null}
61 * @throws IOException in case of IO issue
62 */
63 @Nonnull
64 InputStream openStream() throws IOException;
65
66 /**
67 * Provides a user-friendly hint about the location of the source.
68 * This could be a local file path, a URI or just an empty string.
69 * The intention is to assist users during error reporting.
70 *
71 * @return a user-friendly hint about the location of the source, never {@code null}
72 */
73 @Nonnull
74 String getLocation();
75
76 /**
77 * Returns a new source identified by a relative path. Implementation <strong>MUST</strong>
78 * be able to accept <code>relative</code> parameter values that
79 * <ul>
80 * <li>use either / or \ file path separator,</li>
81 * <li>have .. parent directory references,</li>
82 * <li>point either at file or directory.</li>
83 * </ul>
84 *
85 * @param relative is the path of the requested source relative to this source
86 * @return related source or <code>null</code> if no such source
87 */
88 Source resolve(String relative);
89 }