001// Copyright 2006, 2010, 2011 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007// http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5.services;
016
017import org.apache.tapestry5.ioc.internal.util.InternalUtils;
018
019/**
020 * Used to configure the {@link ComponentClassResolver}, to allow it to map prefixes to library root packages (the
021 * application namespace is a special case of this). In each case, a prefix on the path is mapped to a package. Starting
022 * with Tapestry 5.2, the path prefix may not contain a slash character.
023 * <p/>
024 * The root package name should have a number of sub-packages:
025 * <dl>
026 * <dt>pages</dt>
027 * <dd>contains named pages</dd>
028 * <dt>components</dt>
029 * <dd>contains components</dd>
030 * <dt>mixins</dt>
031 * <dd>contains component mixins</dd>
032 * <dt>base</dt>
033 * <dd>contains base classes</dd>
034 * </dl>
035 */
036public final class LibraryMapping
037{
038    private final String virtualFolderName, rootPackage;
039
040    /**
041     * Maps a virtual folder to a package that contains sub-packages for components, pages, etc. The special pathPrefix
042     * "" (the empty string) identifies the application. Tapestry defines a special pathPrefix, "core", for the core
043     * components.
044     * <p/>
045     * Note that it <em>is</em> allowed to contribute mutiple LibraryMappings with the same prefix to the
046     * {@link ComponentClassResolver}, and the results are merged (though conflicts, where the same simple name appears
047     * under multiple root packages, is not currently checked for).
048     *
049     * @param virtualFolderName identifies the virtual folder "containing" the pages and components of the library. This may contain an embedded slash, but not a leading or trailing slash.
050     * @param rootPackage       The root package to search.
051     */
052    public LibraryMapping(String virtualFolderName, String rootPackage)
053    {
054        assert InternalUtils.isNonBlank(rootPackage);
055
056        if (virtualFolderName.startsWith("/") || virtualFolderName.endsWith("/"))
057        {
058            throw new RuntimeException(
059                    "LibraryMapping path prefixes may not start with or end with a slash.");
060        }
061
062        this.virtualFolderName = virtualFolderName;
063        this.rootPackage = rootPackage;
064    }
065
066    /**
067     * Returns the virtual folder name (the odd name of this method reflects the evolution of the framework).
068     */
069    public String getPathPrefix()
070    {
071        return virtualFolderName;
072    }
073
074    public String getRootPackage()
075    {
076        return rootPackage;
077    }
078
079    @Override
080    public String toString()
081    {
082        return String.format("LibraryMapping[%s, %s]", virtualFolderName, rootPackage);
083    }
084}