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 Maven projects,
35 * models, settings, or toolchains. The source implementation handles
36 * all the details of accessing the underlying content while providing
37 * a uniform API to consumers.
38 * <p>
39 * Sources can represent:
40 * <ul>
41 * <li>Local filesystem files</li>
42 * <li>In-memory content</li>
43 * <li>Database entries</li>
44 * <li>Network resources</li>
45 * </ul>
46 *
47 * @since 4.0.0
48 * @see org.apache.maven.api.services.ProjectBuilder#build(Session, Source)
49 */
50 @Experimental
51 public interface Source {
52 /**
53 * Provides access to the file backing this source, if available.
54 * Not all sources are backed by files - for example, in-memory sources
55 * or database-backed sources will return null.
56 *
57 * @return the underlying {@code Path} if this source is file-backed,
58 * or {@code null} if this source has no associated file
59 */
60 @Nullable
61 Path getPath();
62
63 /**
64 * Creates a new input stream to read the source contents.
65 * Each call creates a fresh stream starting from the beginning.
66 * The caller is responsible for closing the returned stream.
67 *
68 * @return a new input stream positioned at the start of the content
69 * @throws IOException if the stream cannot be created or opened
70 */
71 @Nonnull
72 InputStream openStream() throws IOException;
73
74 /**
75 * Returns a human-readable description of where this source came from,
76 * used primarily for error messages and debugging.
77 * <p>
78 * Examples of locations:
79 * <ul>
80 * <li>Absolute file path: {@code /path/to/pom.xml}</li>
81 * <li>Relative file path: {@code ../parent/pom.xml}</li>
82 * <li>URL: {@code https://repo.maven.org/.../pom.xml}</li>
83 * <li>Description: {@code <memory>} or {@code <database>}</li>
84 * </ul>
85 *
86 * @return a non-null string describing the source location
87 */
88 @Nonnull
89 String getLocation();
90
91 /**
92 * Resolves a new source relative to this one.
93 * <p>
94 * The resolution strategy depends on the source type:
95 * <ul>
96 * <li>File sources resolve against their parent directory</li>
97 * <li>URL sources resolve against their base URL</li>
98 * <li>Other sources may not support resolution and return null</li>
99 * </ul>
100 * <p>
101 * The implementation must handle:
102 * <ul>
103 * <li>Both forward and back slashes as path separators</li>
104 * <li>Parent directory references (..)</li>
105 * <li>Both file and directory targets</li>
106 * </ul>
107 *
108 * @param relative path to resolve relative to this source
109 * @return the resolved source, or null if resolution not possible
110 * @throws NullPointerException if relative is null
111 */
112 @Nullable
113 Source resolve(@Nonnull String relative);
114 }