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.Optional;
23
24 import org.apache.maven.api.annotations.Experimental;
25 import org.apache.maven.api.annotations.Nonnull;
26
27 /**
28 * The option of a command-line tool where to place the paths to some dependencies.
29 * A {@code PathType} can identify the Java class-path, the Java module-path,
30 * or another kind of path for another programming language for example.
31 * Path types are often exclusive. For example, a dependency should not be
32 * both on the Java class-path and on the Java module-path.
33 *
34 * @see org.apache.maven.api.services.DependencyResolverResult#getDispatchedPaths()
35 *
36 * @since 4.0.0
37 */
38 @Experimental
39 public interface PathType {
40 /**
41 * The type for all paths that could not be placed in any of the types requested by a caller.
42 * This type can appear in the return value of a call to
43 * {@link Session#resolveDependencies resolveDependencies(...)} when at least one dependency
44 * cannot be associated to any type specified in the {@code desiredTypes} argument.
45 * Plugins can choose to report a warning to users when unresolved paths exist.
46 */
47 PathType UNRESOLVED = new PathType() {
48 @Override
49 public String name() {
50 return "UNRESOLVED";
51 }
52
53 @Override
54 public String id() {
55 return "UNRESOLVED";
56 }
57
58 @Override
59 public Optional<String> option() {
60 return Optional.empty();
61 }
62
63 @Override
64 public String[] option(Iterable<? extends Path> paths) {
65 return new String[0];
66 }
67 };
68
69 /**
70 * Returns the unique name of this path type, including the module to patch if any.
71 * For example, if this type is {@link JavaPathType#MODULES}, then this method returns {@code "MODULES"}.
72 * But if this type was created by {@code JavaPathType.patchModule("foo.bar")}, then this method returns
73 * {@code "PATCH_MODULE:foo.bar"}.
74 *
75 * @return the programmatic name together with the module name on which it applies
76 * @see #toString()
77 */
78 @Nonnull
79 String id();
80
81 /**
82 * Returns the name of the tool option for this path. For example, if this path type
83 * is {@link JavaPathType#MODULES}, then this method returns {@code "--module-path"}.
84 * The option does not include the {@linkplain JavaPathType.Modular#moduleName() module name}
85 * on which it applies.
86 *
87 * @return the name of the tool option for this path type
88 */
89 @Nonnull
90 Optional<String> option();
91
92 /**
93 * Returns the option followed by a string representation of the given path elements.
94 * The path elements are separated by an option-specific or platform-specific separator.
95 * If the given {@code paths} argument contains no element, then this method returns an empty string.
96 *
97 * <h4>Examples</h4>
98 * If {@code paths} is a list containing two elements, {@code dir/path1} and {@code dir/path2}, then:
99 *
100 * <ul>
101 * <li>If this type is {@link JavaPathType#MODULES}, then this method returns
102 * {@code {"--module-path", "dir/path1:dir/path2"}} on Unix or
103 * {@code {"--module-path", "dir\path1;dir\path2"}} on Windows.</li>
104 * <li>If this type was created by {@code JavaPathType.patchModule("foo.bar")}, then the method returns
105 * {@code {"--patch-module", "foo.bar=dir/path1:dir/path2"}} on Unix or
106 * {@code {"--patch-module", "foo.bar=dir\path1;dir\path2"}} on Windows.</li>
107 * </ul>
108 *
109 * @param paths the path to format as a string
110 * @return the option associated to this path type followed by the given path elements,
111 * or an empty array if there is no path element.
112 */
113 @Nonnull
114 String[] option(Iterable<? extends Path> paths);
115
116 /**
117 * Returns the name of this path type. For example, if this path type
118 * is {@link JavaPathType#MODULES}, then this method returns {@code "MODULES"}.
119 *
120 * @return the programmatic name of this path type
121 */
122 @Nonnull
123 String name();
124
125 /**
126 * {@return a string representation for this extensible enum describing a path type}.
127 * For example {@code "PathType[PATCH_MODULE:foo.bar]"}.
128 */
129 @Nonnull
130 @Override
131 String toString();
132 }