001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.lang3;
018
019/**
020 * Operations regarding the classpath.
021 *
022 * <p>The methods of this class do not allow {@code null} inputs.</p>
023 *
024 * @since 3.3
025 * @version $Id: ClassPathUtils.java 1561722 2014-01-27 16:19:55Z britter $
026 */
027//@Immutable
028public class ClassPathUtils {
029
030    /**
031     * <p>{@code ClassPathUtils} instances should NOT be constructed in
032     * standard programming. Instead, the class should be used as
033     * {@code ClassPathUtils.toFullyQualifiedName(MyClass.class, "MyClass.properties");}.</p>
034     *
035     * <p>This constructor is public to permit tools that require a JavaBean
036     * instance to operate.</p>
037     */
038    public ClassPathUtils() {
039        super();
040    }
041
042    /**
043     * Returns the fully qualified name for the resource with name {@code resourceName} relative to the given context.
044     *
045     * <p>Note that this method does not check whether the resource actually exists.
046     * It only constructs the name.
047     * Null inputs are not allowed.</p>
048     *
049     * <pre>
050     * ClassPathUtils.toFullyQualifiedName(StringUtils.class, "StringUtils.properties") = "org.apache.commons.lang3.StringUtils.properties"
051     * </pre>
052     *
053     * @param context The context for constructing the name.
054     * @param resourceName the resource name to construct the fully qualified name for.
055     * @return the fully qualified name of the resource with name {@code resourceName}.
056     * @throws java.lang.NullPointerException if either {@code context} or {@code resourceName} is null.
057     */
058    public static String toFullyQualifiedName(final Class<?> context, final String resourceName) {
059        Validate.notNull(context, "Parameter '%s' must not be null!", "context" );
060        Validate.notNull(resourceName, "Parameter '%s' must not be null!", "resourceName");
061        return toFullyQualifiedName(context.getPackage(), resourceName);
062    }
063
064    /**
065     * Returns the fully qualified name for the resource with name {@code resourceName} relative to the given context.
066     *
067     * <p>Note that this method does not check whether the resource actually exists.
068     * It only constructs the name.
069     * Null inputs are not allowed.</p>
070     *
071     * <pre>
072     * ClassPathUtils.toFullyQualifiedName(StringUtils.class.getPackage(), "StringUtils.properties") = "org.apache.commons.lang3.StringUtils.properties"
073     * </pre>
074     *
075     * @param context The context for constructing the name.
076     * @param resourceName the resource name to construct the fully qualified name for.
077     * @return the fully qualified name of the resource with name {@code resourceName}.
078     * @throws java.lang.NullPointerException if either {@code context} or {@code resourceName} is null.
079     */
080    public static String toFullyQualifiedName(final Package context, final String resourceName) {
081        Validate.notNull(context, "Parameter '%s' must not be null!", "context" );
082        Validate.notNull(resourceName, "Parameter '%s' must not be null!", "resourceName");
083        StringBuilder sb = new StringBuilder();
084        sb.append(context.getName());
085        sb.append(".");
086        sb.append(resourceName);
087        return sb.toString();
088    }
089
090    /**
091     * Returns the fully qualified path for the resource with name {@code resourceName} relative to the given context.
092     *
093     * <p>Note that this method does not check whether the resource actually exists.
094     * It only constructs the path.
095     * Null inputs are not allowed.</p>
096     *
097     * <pre>
098     * ClassPathUtils.toFullyQualifiedPath(StringUtils.class, "StringUtils.properties") = "org/apache/commons/lang3/StringUtils.properties"
099     * </pre>
100     *
101     * @param context The context for constructing the path.
102     * @param resourceName the resource name to construct the fully qualified path for.
103     * @return the fully qualified path of the resource with name {@code resourceName}.
104     * @throws java.lang.NullPointerException if either {@code context} or {@code resourceName} is null.
105     */
106    public static String toFullyQualifiedPath(final Class<?> context, final String resourceName) {
107        Validate.notNull(context, "Parameter '%s' must not be null!", "context" );
108        Validate.notNull(resourceName, "Parameter '%s' must not be null!", "resourceName");
109        return toFullyQualifiedPath(context.getPackage(), resourceName);
110    }
111
112
113    /**
114     * Returns the fully qualified path for the resource with name {@code resourceName} relative to the given context.
115     *
116     * <p>Note that this method does not check whether the resource actually exists.
117     * It only constructs the path.
118     * Null inputs are not allowed.</p>
119     *
120     * <pre>
121     * ClassPathUtils.toFullyQualifiedPath(StringUtils.class.getPackage(), "StringUtils.properties") = "org/apache/commons/lang3/StringUtils.properties"
122     * </pre>
123     *
124     * @param context The context for constructing the path.
125     * @param resourceName the resource name to construct the fully qualified path for.
126     * @return the fully qualified path of the resource with name {@code resourceName}.
127     * @throws java.lang.NullPointerException if either {@code context} or {@code resourceName} is null.
128     */
129    public static String toFullyQualifiedPath(final Package context, final String resourceName) {
130        Validate.notNull(context, "Parameter '%s' must not be null!", "context" );
131        Validate.notNull(resourceName, "Parameter '%s' must not be null!", "resourceName");
132        StringBuilder sb = new StringBuilder();
133        sb.append(context.getName().replace('.', '/'));
134        sb.append("/");
135        sb.append(resourceName);
136        return sb.toString();
137    }
138
139}