001/* 002 * This library is part of OpenCms - 003 * the Open Source Content Management System 004 * 005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com) 006 * 007 * This library is free software; you can redistribute it and/or 008 * modify it under the terms of the GNU Lesser General Public 009 * License as published by the Free Software Foundation; either 010 * version 2.1 of the License, or (at your option) any later version. 011 * 012 * This library is distributed in the hope that it will be useful, 013 * but WITHOUT ANY WARRANTY; without even the implied warranty of 014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 015 * Lesser General Public License for more details. 016 * 017 * For further information about Alkacon Software, please see the 018 * company website: http://www.alkacon.com 019 * 020 * For further information about OpenCms, please see the 021 * project website: http://www.opencms.org 022 * 023 * You should have received a copy of the GNU Lesser General Public 024 * License along with this library; if not, write to the Free Software 025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 026 */ 027 028package org.opencms.staticexport; 029 030import org.opencms.file.CmsObject; 031 032/** 033 * Allows to configure customized link substitution behavior.<p> 034 * 035 * Using this handler, you can completely customize the behavior of the link substitution.<p> 036 * 037 * This handler is plugged into 038 * {@link CmsLinkManager#substituteLink(org.opencms.file.CmsObject, String, String, boolean)}, 039 * which is the central method to calculate links from VFS paths, 040 * used by the <code><cms:link /></code> tag and the rest of the OpenCms core.<p> 041 * 042 * Moreover, this handler is plugged into 043 * {@link CmsLinkManager#getRootPath(CmsObject, String, String)}, 044 * which is the reverse method to calculate a VFS root path from a link.<p> 045 * 046 * For any implementation of this interface you must ensure the following: 047 * <pre> 048 * // path: String that represents a valid VFS resource root path 049 * // cms: a valid OpenCms user context 050 * String httpLink = OpenCms.getLinkManager().substituteLinkForRootPath(cms, path); 051 * String vfsPath = OpenCms.getLinkManager().getRootPath(cms, httpLink); 052 * path.equals(vfsPath); // this must be true! 053 * </pre> 054 * 055 * The default implementation of this interface is {@link CmsDefaultLinkSubstitutionHandler}.<p> 056 * 057 * @since 7.0.2 058 * 059 * @see CmsLinkManager#substituteLink(org.opencms.file.CmsObject, String, String, boolean) 060 * for the method where this handler is used to create a link from a VFS root path 061 * @see CmsLinkManager#getRootPath(CmsObject, String, String) 062 * for the method where this handler is used to create VFS root path from a link 063 * 064 * @see CmsDefaultLinkSubstitutionHandler 065 * for the default implementation of this interface 066 */ 067public interface I_CmsLinkSubstitutionHandler { 068 069 /** 070 * Returns a link <i>from</i> the URI stored in the provided OpenCms user context 071 * <i>to</i> the VFS resource indicated by the given <code>link</code> and <code>siteRoot</code>, 072 * for use on web pages.<p> 073 * 074 * The result should be an absolute link that contains the configured context path and 075 * servlet name, and in the case of the "online" project it will also be rewritten according to 076 * to the configured static export settings.<p> 077 * 078 * In case <code>link</code> is a relative URI, the current URI contained in the provided 079 * OpenCms user context <code>cms</code> is normally used to make the relative <code>link</code> absolute.<p> 080 * 081 * The provided <code>siteRoot</code> is assumed to be the "home" of the link. 082 * In case the current site of the given OpenCms user context <code>cms</code> is different from the 083 * provided <code>siteRoot</code>, the full server prefix is appended to the result link.<p> 084 * 085 * A server prefix is also added if 086 * <ul> 087 * <li>the link is contained in a normal document and the link references a secure document</li> 088 * <li>the link is contained in a secure document and the link references a normal document</li> 089 * </ul> 090 * 091 * Please note the above text describes the default behavior as implemented by 092 * {@link CmsDefaultLinkSubstitutionHandler}, which can be fully customized using this handler interface.<p> 093 * 094 * @param cms the current OpenCms user context 095 * @param link the link to process which is assumed to point to a VFS resource, with optional parameters 096 * @param siteRoot the site root of the <code>link</code> 097 * @param forceSecure if <code>true</code> generates always an absolute URL (with protocol and server name) for secure links 098 * 099 * @return a link <i>from</i> the URI stored in the provided OpenCms user context 100 * <i>to</i> the VFS resource indicated by the given <code>link</code> and <code>siteRoot</code> 101 * 102 * @see #getRootPath(CmsObject, String, String) for the reverse function, which creates a VFS 103 */ 104 String getLink(CmsObject cms, String link, String siteRoot, boolean forceSecure); 105 106 /** 107 * Returns a link <i>from</i> the URI stored in the provided OpenCms user context 108 * <i>to</i> the VFS resource indicated by the given <code>link</code> and <code>siteRoot</code>, 109 * for use on web pages.<p> 110 * 111 * The result should be an absolute link that contains the configured context path and 112 * servlet name, and in the case of the "online" project it will also be rewritten according to 113 * to the configured static export settings.<p> 114 * 115 * In case <code>link</code> is a relative URI, the current URI contained in the provided 116 * OpenCms user context <code>cms</code> is normally used to make the relative <code>link</code> absolute.<p> 117 * 118 * The provided <code>siteRoot</code> is assumed to be the "home" of the link. 119 * In case the current site of the given OpenCms user context <code>cms</code> is different from the 120 * provided <code>siteRoot</code>, the full server prefix is appended to the result link.<p> 121 * 122 * A server prefix is also added if 123 * <ul> 124 * <li>the link is contained in a normal document and the link references a secure document</li> 125 * <li>the link is contained in a secure document and the link references a normal document</li> 126 * </ul> 127 * 128 * Please note the above text describes the default behavior as implemented by 129 * {@link CmsDefaultLinkSubstitutionHandler}, which can be fully customized using this handler interface.<p> 130 * 131 * @param cms the current OpenCms user context 132 * @param link the link to process which is assumed to point to a VFS resource, with optional parameters 133 * @param siteRoot the site root of the <code>link</code> 134 * @param targetDetailPage the target detail page, in case of linking to a specific detail page 135 * @param forceSecure if <code>true</code> generates always an absolute URL (with protocol and server name) for secure links 136 * 137 * @return a link <i>from</i> the URI stored in the provided OpenCms user context 138 * <i>to</i> the VFS resource indicated by the given <code>link</code> and <code>siteRoot</code> 139 * 140 * @see #getRootPath(CmsObject, String, String) for the reverse function, which creates a VFS 141 */ 142 String getLink(CmsObject cms, String link, String siteRoot, String targetDetailPage, boolean forceSecure); 143 144 /** 145 * Returns the resource root path in the OpenCms VFS for the given target URI link, or <code>null</code> in 146 * case the link points to an external site.<p> 147 * 148 * The default implementation applies the following transformations to the link:<ul> 149 * <li>In case the link starts with a VFS prefix (for example <code>/opencms/opencms</code>, 150 * this prefix is removed from the result 151 * <li>In case the link is not a root path, the current site root is appended to the result.<p> 152 * <li>In case the link is relative, it will be made absolute using the given absolute <code>basePath</code> 153 * as starting point.<p> 154 * <li>In case the link contains a server schema (for example <code>http://www.mysite.de/</code>), 155 * which points to a configured site in OpenCms, the server schema is replaced with 156 * the root path of the site.<p> 157 * <li>In case the link points to an external site, or in case it is not a valid URI, 158 * then <code>null</code> is returned.<p> 159 * </ul> 160 * 161 * Please note the above text describes the default behavior as implemented by 162 * {@link CmsDefaultLinkSubstitutionHandler}, which can be fully customized using this handler interface.<p> 163 * 164 * @param cms the current users OpenCms context 165 * @param targetUri the target URI link 166 * @param basePath path to use as base in case the target URI is relative (can be <code>null</code>) 167 * 168 * @return the resource root path in the OpenCms VFS for the given target URI link, or <code>null</code> in 169 * case the link points to an external site 170 * 171 * @see #getLink(CmsObject, String, String, boolean) for the reverse function, which creates a link 172 * form a VFS resource path 173 */ 174 String getRootPath(CmsObject cms, String targetUri, String basePath); 175}