    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
    015    package org.apache.tapestry5.services;
    016
    017    import 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     */
    036    public 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    }