1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.lang3;
18
19 import java.util.Objects;
20
21 /**
22 * Operations regarding the classpath.
23 *
24 * <p>
25 * The methods of this class do not allow {@code null} inputs.
26 * </p>
27 *
28 * @since 3.3
29 */
30 //@Immutable
31 public class ClassPathUtils {
32
33 /**
34 * Converts a package name to a Java path ('/').
35 *
36 * @param path the source path.
37 * @return a package name.
38 * @throws NullPointerException if {@code path} is null.
39 * @since 3.13.0
40 */
41 public static String packageToPath(final String path) {
42 return Objects.requireNonNull(path, "path").replace('.', '/');
43 }
44
45 /**
46 * Converts a Java path ('/') to a package name.
47 *
48 * @param path the source path.
49 * @return a package name.
50 * @throws NullPointerException if {@code path} is null.
51 * @since 3.13.0
52 */
53 public static String pathToPackage(final String path) {
54 return Objects.requireNonNull(path, "path").replace('/', '.');
55 }
56
57 /**
58 * Returns the fully qualified name for the resource with name {@code resourceName} relative to the given context.
59 *
60 * <p>
61 * Note that this method does not check whether the resource actually exists. It only constructs the name. Null inputs are not allowed.
62 * </p>
63 *
64 * <pre>
65 * ClassPathUtils.toFullyQualifiedName(StringUtils.class, "StringUtils.properties") = "org.apache.commons.lang3.StringUtils.properties"
66 * </pre>
67 *
68 * @param context The context for constructing the name.
69 * @param resourceName the resource name to construct the fully qualified name for.
70 * @return the fully qualified name of the resource with name {@code resourceName}.
71 * @throws NullPointerException if either {@code context} or {@code resourceName} is null.
72 */
73 public static String toFullyQualifiedName(final Class<?> context, final String resourceName) {
74 Objects.requireNonNull(context, "context");
75 Objects.requireNonNull(resourceName, "resourceName");
76 return toFullyQualifiedName(context.getPackage(), resourceName);
77 }
78
79 /**
80 * Returns the fully qualified name for the resource with name {@code resourceName} relative to the given context.
81 *
82 * <p>
83 * Note that this method does not check whether the resource actually exists. It only constructs the name. Null inputs are not allowed.
84 * </p>
85 *
86 * <pre>
87 * ClassPathUtils.toFullyQualifiedName(StringUtils.class.getPackage(), "StringUtils.properties") = "org.apache.commons.lang3.StringUtils.properties"
88 * </pre>
89 *
90 * @param context The context for constructing the name.
91 * @param resourceName the resource name to construct the fully qualified name for.
92 * @return the fully qualified name of the resource with name {@code resourceName}.
93 * @throws NullPointerException if either {@code context} or {@code resourceName} is null.
94 */
95 public static String toFullyQualifiedName(final Package context, final String resourceName) {
96 Objects.requireNonNull(context, "context");
97 Objects.requireNonNull(resourceName, "resourceName");
98 return context.getName() + "." + resourceName;
99 }
100
101 /**
102 * Returns the fully qualified path for the resource with name {@code resourceName} relative to the given context.
103 *
104 * <p>
105 * Note that this method does not check whether the resource actually exists. It only constructs the path. Null inputs are not allowed.
106 * </p>
107 *
108 * <pre>
109 * ClassPathUtils.toFullyQualifiedPath(StringUtils.class, "StringUtils.properties") = "org/apache/commons/lang3/StringUtils.properties"
110 * </pre>
111 *
112 * @param context The context for constructing the path.
113 * @param resourceName the resource name to construct the fully qualified path for.
114 * @return the fully qualified path of the resource with name {@code resourceName}.
115 * @throws NullPointerException if either {@code context} or {@code resourceName} is null.
116 */
117 public static String toFullyQualifiedPath(final Class<?> context, final String resourceName) {
118 Objects.requireNonNull(context, "context");
119 Objects.requireNonNull(resourceName, "resourceName");
120 return toFullyQualifiedPath(context.getPackage(), resourceName);
121 }
122
123 /**
124 * Returns the fully qualified path for the resource with name {@code resourceName} relative to the given context.
125 *
126 * <p>
127 * Note that this method does not check whether the resource actually exists. It only constructs the path. Null inputs are not allowed.
128 * </p>
129 *
130 * <pre>
131 * ClassPathUtils.toFullyQualifiedPath(StringUtils.class.getPackage(), "StringUtils.properties") = "org/apache/commons/lang3/StringUtils.properties"
132 * </pre>
133 *
134 * @param context The context for constructing the path.
135 * @param resourceName the resource name to construct the fully qualified path for.
136 * @return the fully qualified path of the resource with name {@code resourceName}.
137 * @throws NullPointerException if either {@code context} or {@code resourceName} is null.
138 */
139 public static String toFullyQualifiedPath(final Package context, final String resourceName) {
140 Objects.requireNonNull(context, "context");
141 Objects.requireNonNull(resourceName, "resourceName");
142 return packageToPath(context.getName()) + "/" + resourceName;
143 }
144
145 /**
146 * {@link ClassPathUtils} instances should NOT be constructed in standard programming. Instead, the class should be used as
147 * {@code ClassPathUtils.toFullyQualifiedName(MyClass.class, "MyClass.properties");}.
148 *
149 * <p>
150 * This constructor is public to permit tools that require a JavaBean instance to operate.
151 * </p>
152 *
153 * @deprecated TODO Make private in 4.0.
154 */
155 @Deprecated
156 public ClassPathUtils() {
157 // empty
158 }
159
160 }