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;
20
21 import java.nio.file.Path;
22 import java.util.List;
23 import java.util.Optional;
24
25 import org.apache.maven.api.annotations.Experimental;
26 import org.apache.maven.api.annotations.Nonnull;
27 import org.apache.maven.api.model.Build;
28 import org.apache.maven.api.model.Model;
29
30 /**
31 * Interface representing a Maven project which can be created using the
32 * {@link org.apache.maven.api.services.ProjectBuilder ProjectBuilder} service.
33 * Such objects are immutable and plugin that wish to modify such objects
34 * need to do so using the {@link org.apache.maven.api.services.ProjectManager
35 * ProjectManager} service.
36 * <p>
37 * Projects are created using the {@code ProjectBuilder} from a POM file
38 * (usually named {@code pom.xml}) on the file system.
39 * The {@link #getPomPath()} will point to the POM file and the
40 * {@link #getBasedir()} to the directory parent containing the
41 * POM file.
42 * </p>
43 *
44 * @since 4.0.0
45 * @see org.apache.maven.api.services.ProjectManager
46 * @see org.apache.maven.api.services.ProjectBuilder
47 */
48 @Experimental
49 public interface Project {
50
51 /**
52 * Returns the project groupId.
53 */
54 @Nonnull
55 String getGroupId();
56
57 /**
58 * Returns the project artifactId.
59 */
60 @Nonnull
61 String getArtifactId();
62
63 /**
64 * Returns the project version.
65 */
66 @Nonnull
67 String getVersion();
68
69 /**
70 * Returns the project packaging.
71 * <p>
72 * Note: unlike in legacy code, logical checks against string representing packaging (returned by this method)
73 * are NOT recommended (code like {@code "pom".equals(project.getPackaging)} must be avoided). Use method
74 * {@link #getArtifacts()} to gain access to POM or build artifact.
75 *
76 * @see #getArtifacts()
77 */
78 @Nonnull
79 Packaging getPackaging();
80
81 /**
82 * Returns the project language. It is by default determined by {@link #getPackaging()}.
83 *
84 * @see #getPackaging()
85 */
86 @Nonnull
87 default Language getLanguage() {
88 return getPackaging().language();
89 }
90
91 /**
92 * Returns the project POM artifact, which is the artifact of the POM of this project. Every project have a POM
93 * artifact, even if the existence of backing POM file is NOT a requirement (i.e. for some transient projects).
94 *
95 * @see org.apache.maven.api.services.ArtifactManager#getPath(Artifact)
96 */
97 @Nonnull
98 default ProducedArtifact getPomArtifact() {
99 return getArtifacts().get(0);
100 }
101
102 /**
103 * Returns the project main artifact, which is the artifact produced by this project build, if applicable.
104 * This artifact MAY be absent if the project is actually not producing any main artifact (i.e. "pom" packaging).
105 *
106 * @see #getPackaging()
107 * @see org.apache.maven.api.services.ArtifactManager#getPath(Artifact)
108 */
109 @Nonnull
110 default Optional<ProducedArtifact> getMainArtifact() {
111 List<ProducedArtifact> artifacts = getArtifacts();
112 return artifacts.size() == 2 ? Optional.of(artifacts.get(1)) : Optional.empty();
113 }
114
115 /**
116 * Returns the project artifacts as immutable list. Elements are the project POM artifact and the artifact
117 * produced by this project build, if applicable. Hence, the returned list may have one or two elements
118 * (never less than 1, never more than 2), depending on project packaging.
119 * <p>
120 * The list's first element is ALWAYS the project POM artifact. Presence of second element in the list depends
121 * solely on the project packaging.
122 *
123 * @see #getPackaging()
124 * @see #getPomArtifact()
125 * @see #getMainArtifact()
126 * @see org.apache.maven.api.services.ArtifactManager#getPath(Artifact)
127 */
128 @Nonnull
129 List<ProducedArtifact> getArtifacts();
130
131 /**
132 * Returns the project model.
133 */
134 @Nonnull
135 Model getModel();
136
137 /**
138 * Shorthand method.
139 */
140 @Nonnull
141 default Build getBuild() {
142 Build build = getModel().getBuild();
143 return build != null ? build : Build.newInstance();
144 }
145
146 /**
147 * Returns the path to the pom file for this project.
148 * A project is usually read from a file named {@code pom.xml},
149 * which contains the {@linkplain #getModel() model} in an XML form.
150 * When a custom {@code org.apache.maven.api.spi.ModelParser} is used,
151 * the path may point to a non XML file.
152 * <p>
153 * The POM path is also used to define the {@linkplain #getBasedir() base directory}
154 * of the project.
155 *
156 * @return the path of the pom
157 * @see #getBasedir()
158 */
159 @Nonnull
160 Path getPomPath();
161
162 /**
163 * Returns the project base directory, i.e. the directory containing the project.
164 * A project is usually read from the file system and this will point to
165 * the directory containing the POM file.
166 *
167 * @return the path of the directory containing the project
168 */
169 @Nonnull
170 Path getBasedir();
171
172 /**
173 * Returns the project direct dependencies (directly specified or inherited).
174 */
175 @Nonnull
176 List<DependencyCoordinates> getDependencies();
177
178 /**
179 * Returns the project managed dependencies (directly specified or inherited).
180 */
181 @Nonnull
182 List<DependencyCoordinates> getManagedDependencies();
183
184 /**
185 * Returns the project ID, usable as key.
186 */
187 @Nonnull
188 default String getId() {
189 return getModel().getId();
190 }
191
192 /**
193 * Returns a boolean indicating if the project is the top level project for
194 * this reactor build. The top level project may be different from the
195 * {@code rootDirectory}, especially if a subtree of the project is being
196 * built, either because Maven has been launched in a subdirectory or using
197 * a {@code -f} option.
198 *
199 * @return {@code true} if the project is the top level project for this build
200 */
201 boolean isTopProject();
202
203 /**
204 * Returns a boolean indicating if the project is a root project,
205 * meaning that the {@link #getRootDirectory()} and {@link #getBasedir()}
206 * points to the same directory, and that either {@link Model#isRoot()}
207 * is {@code true} or that {@code basedir} contains a {@code .mvn} child
208 * directory.
209 *
210 * @return {@code true} if the project is the root project
211 * @see Model#isRoot()
212 */
213 boolean isRootProject();
214
215 /**
216 * Gets the root directory of the project, which is the parent directory
217 * containing the {@code .mvn} directory or flagged with {@code root="true"}.
218 *
219 * @throws IllegalStateException if the root directory could not be found
220 * @see Session#getRootDirectory()
221 */
222 @Nonnull
223 Path getRootDirectory();
224
225 /**
226 * Returns project parent project, if any.
227 * <p>
228 * Note that the model may have a parent defined, but an empty parent
229 * project may be returned if the parent comes from a remote repository,
230 * as a {@code Project} must refer to a buildable project.
231 *
232 * @return an optional containing the parent project
233 * @see Model#getParent()
234 */
235 @Nonnull
236 Optional<Project> getParent();
237 }