diff --git a/src/changes/changes.xml b/src/changes/changes.xml index 918b48a26..e43438bc1 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -22,6 +22,7 @@ + New class ClassPathUtils with methods for turning FQN into resource path Move Documentation from user guide to package-info files Convert package.html files to package-info.java files FastDateParser does not handle two digit year parsing like SimpleDateFormat diff --git a/src/main/java/org/apache/commons/lang3/ClassPathUtils.java b/src/main/java/org/apache/commons/lang3/ClassPathUtils.java new file mode 100644 index 000000000..54d907c8c --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/ClassPathUtils.java @@ -0,0 +1,137 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.lang3; + +/** + * Operations regarding the classpath. + * + * @since 3.3 + * @version $Id$ + */ +//@Immutable +public final class ClassPathUtils { + + /** + *

{@code ClassPathUtils} instances should NOT be constructed in + * standard programming. Instead, the class should be used as + * {@code ClassPathUtils.toFullyQualifiedName(MyClass.class, MyClass.properties);}.

+ * + *

This constructor is public to permit tools that require a JavaBean + * instance to operate.

+ */ + public ClassPathUtils() { + super(); + } + + /** + * Returns the fully qualified name for the resource with name {@code resourceName} relative to the given context. + * + *

Note that this method does not check whether the resource actually exists. + * It only constructs the name. + * Null inputs are not allowed.

+ * + * 
+     * ClassPathUtils.toFullyQualifiedName(StringUtils.class, "StringUtils.properties") = "org.apache.commons.lang3.StringUtils.properties"
+     *
+ * + * @param context The context for constructing the name. + * @param resourceName the resource name to construct the fully qualified name for. + * @return the fully qualified name of the resource with name {@code resourceName}. + * @throws java.lang.NullPointerException if either {@code context} or {@code resourceName} is null. + */ + public static String toFullyQualifiedName(final Class context, final String resourceName) { + Validate.notNull(context, "Parameter '%s' must not be null!", "context" ); + Validate.notNull(resourceName, "Parameter '%s' must not be null!", "resourceName"); + return toFullyQualifiedName(context.getPackage(), resourceName); + } + + /** + * Returns the fully qualified name for the resource with name {@code resourceName} relative to the given context. + * + *

Note that this method does not check whether the resource actually exists. + * It only constructs the name. + * Null inputs are not allowed.

+ * + * 
+     * ClassPathUtils.toFullyQualifiedName(StringUtils.class.getPackage(), "StringUtils.properties") = "org.apache.commons.lang3.StringUtils.properties"
+     *
+ * + * @param context The context for constructing the name. + * @param resourceName the resource name to construct the fully qualified name for. + * @return the fully qualified name of the resource with name {@code resourceName}. + * @throws java.lang.NullPointerException if either {@code context} or {@code resourceName} is null. + */ + public static String toFullyQualifiedName(final Package context, final String resourceName) { + Validate.notNull(context, "Parameter '%s' must not be null!", "context" ); + Validate.notNull(resourceName, "Parameter '%s' must not be null!", "resourceName"); + StringBuilder sb = new StringBuilder(); + sb.append(context.getName()); + sb.append("."); + sb.append(resourceName); + return sb.toString(); + } + + /** + * Returns the fully qualified path for the resource with name {@code resourceName} relative to the given context. + * + *

Note that this method does not check whether the resource actually exists. + * It only constructs the path. + * Null inputs are not allowed.

+ * + * 
+     * ClassPathUtils.toFullyQualifiedPath(StringUtils.class, "StringUtils.properties") = "org/apache/commons/lang3/StringUtils.properties"
+     *
+ * + * @param context The context for constructing the path. + * @param resourceName the resource name to construct the fully qualified path for. + * @return the fully qualified path of the resource with name {@code resourceName}. + * @throws java.lang.NullPointerException if either {@code context} or {@code resourceName} is null. + */ + public static String toFullyQualifiedPath(final Class context, final String resourceName) { + Validate.notNull(context, "Parameter '%s' must not be null!", "context" ); + Validate.notNull(resourceName, "Parameter '%s' must not be null!", "resourceName"); + return toFullyQualifiedPath(context.getPackage(), resourceName); + } + + + /** + * Returns the fully qualified path for the resource with name {@code resourceName} relative to the given context. + * + *

Note that this method does not check whether the resource actually exists. + * It only constructs the path. + * Null inputs are not allowed.

+ * + * 
+     * ClassPathUtils.toFullyQualifiedPath(StringUtils.class.getPackage(), "StringUtils.properties") = "org/apache/commons/lang3/StringUtils.properties"
+     *
+ * + * @param context The context for constructing the path. + * @param resourceName the resource name to construct the fully qualified path for. + * @return the fully qualified path of the resource with name {@code resourceName}. + * @throws java.lang.NullPointerException if either {@code context} or {@code resourceName} is null. + */ + public static String toFullyQualifiedPath(final Package context, final String resourceName) { + Validate.notNull(context, "Parameter '%s' must not be null!", "context" ); + Validate.notNull(resourceName, "Parameter '%s' must not be null!", "resourceName"); + StringBuilder sb = new StringBuilder(); + sb.append(context.getName().replace('.', '/')); + sb.append("/"); + sb.append(resourceName); + return sb.toString(); + } + +} diff --git a/src/test/java/org/apache/commons/lang3/ClassPathUtilsTest.java b/src/test/java/org/apache/commons/lang3/ClassPathUtilsTest.java new file mode 100644 index 000000000..c71fc0fe3 --- /dev/null +++ b/src/test/java/org/apache/commons/lang3/ClassPathUtilsTest.java @@ -0,0 +1,99 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.lang3; + +import static org.junit.Assert.assertEquals; + +import org.junit.Test; + +/** + * @version $Id$ + */ +public class ClassPathUtilsTest { + + @Test(expected = NullPointerException.class) + public void testToFullyQualifiedNameNullClassString() throws Exception { + ClassPathUtils.toFullyQualifiedName((Class) null, "Test.properties"); + } + + @Test(expected = NullPointerException.class) + public void testToFullyQualifiedNameClassNull() throws Exception { + ClassPathUtils.toFullyQualifiedName(ClassPathUtils.class, null); + } + + @Test + public void testToFullyQualifiedNameClassString() throws Exception { + String expected = "org.apache.commons.lang3.Test.properties"; + String actual = ClassPathUtils.toFullyQualifiedName(ClassPathUtils.class, "Test.properties"); + + assertEquals(expected, actual); + } + + @Test(expected = NullPointerException.class) + public void testToFullyQualifiedNameNullPackageString() throws Exception { + ClassPathUtils.toFullyQualifiedName((Package) null, "Test.properties"); + } + + @Test(expected = NullPointerException.class) + public void testToFullyQualifiedNamePackageNull() throws Exception { + ClassPathUtils.toFullyQualifiedName(ClassPathUtils.class.getPackage(), null); + } + + @Test + public void testToFullyQualifiedNamePackageString() throws Exception { + String expected = "org.apache.commons.lang3.Test.properties"; + String actual = ClassPathUtils.toFullyQualifiedName(ClassPathUtils.class.getPackage(), "Test.properties"); + + assertEquals(expected, actual); + } + + @Test(expected = NullPointerException.class) + public void testToFullyQualifiedPathClassNullString() throws Exception { + ClassPathUtils.toFullyQualifiedPath((Class) null, "Test.properties"); + } + + @Test(expected = NullPointerException.class) + public void testToFullyQualifiedPathClassNull() throws Exception { + ClassPathUtils.toFullyQualifiedPath(ClassPathUtils.class, null); + } + + @Test + public void testToFullyQualifiedPathClass() throws Exception { + String expected = "org/apache/commons/lang3/Test.properties"; + String actual = ClassPathUtils.toFullyQualifiedPath(ClassPathUtils.class, "Test.properties"); + + assertEquals(expected, actual); + } + + @Test(expected = NullPointerException.class) + public void testToFullyQualifiedPathPackageNullString() throws Exception { + ClassPathUtils.toFullyQualifiedPath((Package) null, "Test.properties"); + } + + @Test(expected = NullPointerException.class) + public void testToFullyQualifiedPathPackageNull() throws Exception { + ClassPathUtils.toFullyQualifiedPath(ClassPathUtils.class.getPackage(), null); + } + + @Test + public void testToFullyQualifiedPathPackage() throws Exception { + String expected = "org/apache/commons/lang3/Test.properties"; + String actual = ClassPathUtils.toFullyQualifiedPath(ClassPathUtils.class.getPackage(), "Test.properties"); + + assertEquals(expected, actual); + } +}