001/*
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.
018*/
019package org.apache.wiki.plugin;
020
021import org.apache.logging.log4j.LogManager;
022import org.apache.logging.log4j.Logger;
023import org.apache.wiki.api.core.Context;
024import org.apache.wiki.api.core.ContextEnum;
025import org.apache.wiki.api.core.Engine;
026import org.apache.wiki.api.core.Page;
027import org.apache.wiki.api.exceptions.PluginException;
028import org.apache.wiki.api.plugin.Plugin;
029import org.apache.wiki.pages.PageManager;
030import org.apache.wiki.references.ReferenceManager;
031import org.apache.wiki.util.TextUtil;
032
033import java.util.ArrayList;
034import java.util.Collection;
035import java.util.HashSet;
036import java.util.Locale;
037import java.util.Map;
038import java.util.ResourceBundle;
039import java.util.regex.Pattern;
040import java.util.regex.PatternSyntaxException;
041import org.apache.wiki.util.TimeLimitedRegex;
042
043
044/**
045 *  Displays the pages referring to the current page.
046 *
047 *  <p>Parameters</p>
048 *  <ul>
049 *    <li><b>name</b> - Name of the root page. Default name of calling page
050 *    <li><b>type</b> - local|externalattachment
051 *    <li><b>depth</b> - How many levels of pages to be parsed.
052 *    <li><b>include</b> - Include only these pages. (eg. include='UC.*|BP.*' )
053 *    <li><b>exclude</b> - Exclude with this pattern. (eg. exclude='LeftMenu' )
054 *    <li><b>format</b> -  full|compact, FULL now expands all levels correctly
055 *  </ul>
056 *
057 */
058public class ReferredPagesPlugin implements Plugin {
059
060    private static final Logger LOG = LogManager.getLogger( ReferredPagesPlugin.class );
061    private Engine m_engine;
062    private int m_depth;
063    private final HashSet< String > m_exists  = new HashSet<>();
064    private final StringBuffer m_result  = new StringBuffer( 1024 );
065    private Pattern m_includePattern;
066    private Pattern m_excludePattern;
067    private int items;
068    private boolean m_formatCompact = true;
069    private boolean m_formatSort;
070
071    /** The parameter name for the root page to start from.  Value is <tt>{@value}</tt>. */
072    public static final String PARAM_ROOT = "page";
073
074    /** The parameter name for the depth.  Value is <tt>{@value}</tt>. */
075    public static final String PARAM_DEPTH = "depth";
076
077    /** The parameter name for the type of the references.  Value is <tt>{@value}</tt>. */
078    public static final String PARAM_TYPE = "type";
079
080    /** The parameter name for the included pages.  Value is <tt>{@value}</tt>. */
081    public static final String PARAM_INCLUDE = "include";
082
083    /** The parameter name for the excluded pages.  Value is <tt>{@value}</tt>. */
084    public static final String PARAM_EXCLUDE = "exclude";
085
086    /** The parameter name for the format.  Value is <tt>{@value}</tt>. */
087    public static final String PARAM_FORMAT = "format";
088
089    /** Parameter name for setting the number of columns that will be displayed by the plugin.  Value is <tt>{@value}</tt>. Available since 2.11.0. */
090    public static final String PARAM_COLUMNS = "columns";
091
092    /** The minimum depth. Value is <tt>{@value}</tt>. */
093    public static final int MIN_DEPTH = 1;
094
095    /** The maximum depth. Value is <tt>{@value}</tt>. */
096    public static final int MAX_DEPTH = 8;
097
098    @Override
099    public String getDisplayName(Locale locale) {
100        final ResourceBundle rb = ResourceBundle.getBundle(PluginManager.PLUGIN_I18N_RESOURCE, locale);
101        return rb.getString(this.getClass().getSimpleName());
102    }
103    
104    @Override
105    public String getSnipExample() {
106        return "ReferredPagesPlugin page='{pagename}' type='local|external|attachment' depth='1..8' include='regexp' exclude='regexp'";
107    }
108    
109    /**
110     *  {@inheritDoc}
111     */
112    @Override
113    public String execute( final Context context, final Map< String, String > params ) throws PluginException {
114        m_engine = context.getEngine();
115        final Page page = context.getPage();
116        if( page == null ) {
117            return "";
118        }
119
120        // parse parameters
121        String rootname = params.get( PARAM_ROOT );
122        if( rootname == null ) {
123            rootname = page.getName() ;
124        }
125        // the links of a page that the viewer may not view are not shown either
126        if( !AbstractReferralPlugin.mayView( context, rootname ) ) {
127            return "";
128        }
129
130        String format = params.get( PARAM_FORMAT );
131        if( format == null) {
132            format = "";
133        }
134        if( format.contains( "full" ) ) {
135            m_formatCompact = false ;
136        }
137        if( format.contains( "sort" ) ) {
138            m_formatSort = true  ;
139        }
140
141        m_depth = TextUtil.parseIntParameter( params.get( PARAM_DEPTH ), MIN_DEPTH );
142        if( m_depth > MAX_DEPTH ) {
143            m_depth = MAX_DEPTH;
144        }
145
146        String includePattern = params.get(PARAM_INCLUDE);
147        if( includePattern == null ) {
148            includePattern = ".*";
149        }
150
151        String excludePattern = params.get(PARAM_EXCLUDE);
152        if( excludePattern == null ) {
153            excludePattern = "^$";
154        }
155
156        final String columns = params.get( PARAM_COLUMNS );
157        if( columns != null ) {
158            items = TextUtil.parseIntParameter( columns, 0 );
159        }
160
161        LOG.debug( "Fetching referred pages for "+ rootname +
162                   " with a depth of "+ m_depth +
163                   " with include pattern of "+ includePattern +
164                   " with exclude pattern of "+ excludePattern +
165                   " with " + columns + " items" );
166
167        //
168        // do the actual work
169        //
170        final String href  = context.getViewURL( rootname );
171        final String title = "ReferredPagesPlugin: depth[" + m_depth +
172                             "] include[" + includePattern + "] exclude[" + excludePattern +
173                             "] format[" + ( m_formatCompact ? "compact" : "full" ) +
174                             ( m_formatSort ? " sort" : "" ) + "]";
175
176        if( items > 1 ) {
177            m_result.append( "<div class=\"ReferredPagesPlugin\" style=\"" )
178                    .append( "columns:" ).append( columns ).append( ";" )
179                    .append( "moz-columns:" ).append( columns ).append( ";" )
180                    .append( "webkit-columns:" ).append( columns ).append( ";" )
181                    .append( "\">\n" );
182        } else {
183            m_result.append( "<div class=\"ReferredPagesPlugin\">\n" );
184        }
185        m_result.append( "<a class=\"wikipage\" href=\"" )
186                .append( href ).append( "\" title=\"" )
187                .append( TextUtil.replaceEntities( title ) )
188                .append( "\">" )
189                .append( TextUtil.replaceEntities( rootname ) )
190                .append( "</a>\n" );
191        m_exists.add( rootname );
192
193        // pre compile all needed patterns
194        // glob compiler :  * is 0..n instance of any char  -- more convenient as input
195        // perl5 compiler : .* is 0..n instances of any char -- more powerful
196        //PatternCompiler g_compiler = new GlobCompiler();
197
198        try {
199             m_includePattern = Pattern.compile( includePattern );
200            m_excludePattern = Pattern.compile( excludePattern );
201           // m_includePattern = compiler.compile( includePattern );
202           // m_excludePattern = compiler.compile( excludePattern );
203        } catch( final PatternSyntaxException e ) {
204            if( m_includePattern == null ) {
205                throw new PluginException( "Illegal include pattern detected." );
206            } else if( m_excludePattern == null ) {
207                throw new PluginException( "Illegal exclude pattern detected." );
208            } else {
209                throw new PluginException( "Illegal internal pattern detected." );
210            }
211        }
212
213        // go get all referred links
214        getReferredPages(context,rootname, 0);
215
216        // close and finish
217        m_result.append ("</div>\n" ) ;
218
219        return m_result.toString() ;
220    }
221
222    /**
223     * Retrieves a list of all referred pages. Is called recursively depending on the depth parameter.
224     */
225    private void getReferredPages( final Context context, final String pagename, int depth ) {
226        if( depth >= m_depth ) {
227            return;  // end of recursion
228        }
229        if( pagename == null ) {
230            return;
231        }
232        if( !m_engine.getManager( PageManager.class ).wikiPageExists(pagename) ) {
233            return;
234        }
235
236        final ReferenceManager mgr = m_engine.getManager( ReferenceManager.class );
237        final Collection< String > allPages = mgr.findRefersTo( pagename );
238        handleLinks( context, allPages, ++depth, pagename );
239    }
240
241    private void handleLinks( final Context context, final Collection<String> links, final int depth, final String pagename ) {
242        boolean isUL = false;
243        final HashSet< String > localLinkSet = new HashSet<>();  // needed to skip multiple links to the same page
244        localLinkSet.add( pagename );
245
246        final ArrayList< String > allLinks = new ArrayList<>();
247
248        if( links != null )
249            allLinks.addAll( links );
250
251        if( m_formatSort ) context.getEngine().getManager( PageManager.class ).getPageSorter().sort( allLinks );
252
253        for( final String link : allLinks ) {
254            if( localLinkSet.contains( link ) ) {
255                continue; // skip multiple links to the same page
256            }
257            localLinkSet.add( link );
258
259            if( !m_engine.getManager( PageManager.class ).wikiPageExists( link ) ) {
260                continue; // hide links to non-existing pages
261            }
262            if( !AbstractReferralPlugin.mayView( context, link ) ) {
263                continue; // hide the pages that the viewer may not view
264            }
265            // author-controlled patterns: time-box each match so a pathological
266            // regexp can't pin the rendering thread (see TimeLimitedRegex)
267            if (TimeLimitedRegex.matches(link, m_excludePattern)) {
268                continue;
269            }
270            if (!TimeLimitedRegex.matches(link, m_includePattern)) {
271                continue;
272            }
273
274            if( m_exists.contains( link ) ) {
275                if( !m_formatCompact ) {
276                    if( !isUL ) {
277                        isUL = true;
278                        m_result.append("<ul>\n");
279                    }
280
281                    //See https://www.w3.org/wiki/HTML_lists  for proper nesting of UL and LI
282                    m_result.append( "<li> " ).append( TextUtil.replaceEntities( link ) ).append( "\n" );
283                    getReferredPages( context, link, depth );  // added recursive call - on general request
284                    m_result.append( "\n</li>\n" );
285                }
286            } else {
287                if( !isUL ) {
288                    isUL = true;
289                    m_result.append("<ul>\n");
290                }
291
292                final String href = context.getURL( ContextEnum.PAGE_VIEW.getRequestContext(), link );
293                m_result.append( "<li><a class=\"wikipage\" href=\"" ).append( href ).append( "\">" ).append( TextUtil.replaceEntities( link ) ).append( "</a>\n" );
294                m_exists.add( link );
295                getReferredPages( context, link, depth );
296                m_result.append( "\n</li>\n" );
297            }
298        }
299
300        if( isUL ) {
301            m_result.append("</ul>\n");
302        }
303    }
304
305}