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.commons.lang3.StringUtils;
022import org.apache.logging.log4j.LogManager;
023import org.apache.logging.log4j.Logger;
024import org.apache.oro.text.GlobCompiler;
025import org.apache.oro.text.regex.MalformedPatternException;
026import org.apache.oro.text.regex.Pattern;
027import org.apache.oro.text.regex.PatternCompiler;
028import org.apache.oro.text.regex.PatternMatcher;
029import org.apache.oro.text.regex.Perl5Matcher;
030import org.apache.wiki.StringTransmutator;
031import org.apache.wiki.api.core.Context;
032import org.apache.wiki.api.core.Engine;
033import org.apache.wiki.api.core.Page;
034import org.apache.wiki.api.exceptions.PluginException;
035import org.apache.wiki.api.plugin.Plugin;
036import org.apache.wiki.auth.AuthorizationManager;
037import org.apache.wiki.auth.permissions.PermissionFactory;
038import org.apache.wiki.pages.PageManager;
039import org.apache.wiki.pages.PageSorter;
040import org.apache.wiki.parser.MarkupParser;
041import org.apache.wiki.parser.WikiDocument;
042import org.apache.wiki.preferences.Preferences;
043import org.apache.wiki.preferences.Preferences.TimeFormat;
044import org.apache.wiki.references.ReferenceManager;
045import org.apache.wiki.render.RenderingManager;
046import org.apache.wiki.util.TextUtil;
047import org.apache.wiki.util.comparators.CollatorComparator;
048import org.apache.wiki.util.comparators.HumanComparator;
049import org.apache.wiki.util.comparators.JavaNaturalComparator;
050import org.apache.wiki.util.comparators.LocaleComparator;
051
052import java.io.IOException;
053import java.text.Collator;
054import java.text.ParseException;
055import java.text.RuleBasedCollator;
056import java.text.SimpleDateFormat;
057import java.util.ArrayList;
058import java.util.Arrays;
059import java.util.Collection;
060import java.util.Date;
061import java.util.Iterator;
062import java.util.List;
063import java.util.Map;
064import java.util.stream.Collectors;
065
066/**
067 *  This is a base class for all plugins using referral things.
068 *
069 *  <p>Parameters (also valid for all subclasses of this class) : </p>
070 *  <ul>
071 *  <li><b>maxwidth</b> - maximum width of generated links</li>
072 *  <li><b>separator</b> - separator between generated links (wikitext)</li>
073 *  <li><b>after</b> - output after the link</li>
074 *  <li><b>before</b> - output before the link</li>
075 *  <li><b>exclude</b> -  a regular expression of pages to exclude from the list. </li>
076 *  <li><b>include</b> -  a regular expression of pages to include in the list. </li>
077 *  <li><b>show</b> - value is either "pages" (default) or "count".  When "count" is specified, shows only the count
078 *      of pages which match. (since 2.8)</li>
079 *  <li><b>columns</b> - How many columns should the output be displayed on.</li>
080 *  <li><b>showLastModified</b> - When show=count, shows also the last modified date. (since 2.8)</li>
081 *  <li><b>sortOrder</b> - specifies the sort order for the resulting list.  Options are
082 *  'human', 'java', 'locale' or a <code>RuleBasedCollator</code> rule string. (since 2.8.3)</li>
083 *  </ul>
084 *
085 */
086public abstract class AbstractReferralPlugin implements Plugin {
087
088    private static final Logger LOG = LogManager.getLogger( AbstractReferralPlugin.class );
089
090    /** Magic value for rendering all items. */
091    public static final int    ALL_ITEMS              = -1;
092
093    /** Parameter name for setting the maximum width.  Value is <tt>{@value}</tt>. */
094    public static final String PARAM_MAXWIDTH         = "maxwidth";
095
096    /** Parameter name for the separator string.  Value is <tt>{@value}</tt>. */
097    public static final String PARAM_SEPARATOR        = "separator";
098
099    /** Parameter name for the output after the link.  Value is <tt>{@value}</tt>. */
100    public static final String PARAM_AFTER            = "after";
101
102    /** Parameter name for the output before the link.  Value is <tt>{@value}</tt>. */
103    public static final String PARAM_BEFORE           = "before";
104
105    /** Parameter name for setting the list of excluded patterns.  Value is <tt>{@value}</tt>. */
106    public static final String PARAM_EXCLUDE          = "exclude";
107
108    /** Parameter name for setting the list of included patterns.  Value is <tt>{@value}</tt>. */
109    public static final String PARAM_INCLUDE          = "include";
110
111    /** Parameter name for the show parameter.  Value is <tt>{@value}</tt>. */
112    public static final String PARAM_SHOW             = "show";
113
114    /** Parameter name for setting show to "pages".  Value is <tt>{@value}</tt>. */
115    public static final String PARAM_SHOW_VALUE_PAGES = "pages";
116
117    /** Parameter name for setting show to "count".  Value is <tt>{@value}</tt>. */
118    public static final String PARAM_SHOW_VALUE_COUNT = "count";
119
120    /** Parameter name for showing the last modification count.  Value is <tt>{@value}</tt>. */
121    public static final String PARAM_LASTMODIFIED     = "showLastModified";
122
123    /** 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. */
124    public static final String PARAM_COLUMNS          = "columns";
125
126    /** Parameter name for specifying the sort order.  Value is <tt>{@value}</tt>. */
127    protected static final String PARAM_SORTORDER        = "sortOrder";
128    protected static final String PARAM_SORTORDER_HUMAN  = "human";
129    protected static final String PARAM_SORTORDER_JAVA   = "java";
130    protected static final String PARAM_SORTORDER_LOCALE = "locale";
131
132    protected int m_maxwidth = Integer.MAX_VALUE;
133    protected String m_before = ""; // null not blank
134    protected String m_separator = ""; // null not blank
135    protected String m_after = "\\\\";
136    protected int items;
137
138    protected Pattern[]  m_exclude;
139    protected Pattern[]  m_include;
140    protected PageSorter m_sorter;
141
142    protected String m_show = "pages";
143    protected boolean m_lastModified;
144    // the last modified date of the page that has been last modified:
145    protected Date m_dateLastModified = new Date(0);
146    protected SimpleDateFormat m_dateFormat;
147
148    protected Engine m_engine;
149
150    /**
151     * @param context the wiki context
152     * @param params parameters for initializing the plugin
153     * @throws PluginException if any of the plugin parameters are malformed
154     */
155    // FIXME: The compiled pattern strings should really be cached somehow.
156    public void initialize( final Context context, final Map< String, String > params ) throws PluginException {
157        m_dateFormat = Preferences.getDateFormat( context, TimeFormat.DATETIME );
158        m_engine = context.getEngine();
159        m_maxwidth = TextUtil.parseIntParameter( params.get( PARAM_MAXWIDTH ), Integer.MAX_VALUE );
160        if( m_maxwidth < 0 ) {
161            m_maxwidth = 0;
162        }
163
164        String s = params.get( PARAM_SEPARATOR );
165        if( s != null ) {
166            m_separator = TextUtil.replaceEntities( s );
167            // pre-2.1.145 there was a separator at the end of the list
168            // if they set the parameters, we use the new format of
169            // before Item1 after separator before Item2 after separator before Item3 after
170            m_after = "";
171        }
172
173        s = params.get( PARAM_BEFORE );
174        if( s != null ) {
175            m_before = s;
176        }
177
178        s = params.get( PARAM_AFTER );
179        if( s != null ) {
180            m_after = s;
181        }
182
183        s = params.get( PARAM_COLUMNS );
184        if( s!= null ) {
185            items = TextUtil.parseIntParameter( s, 0 );
186        }
187
188        s = params.get( PARAM_EXCLUDE );
189        if ( s != null ) {
190            try {
191                final PatternCompiler pc = new GlobCompiler();
192                final String[] ptrns = StringUtils.split( s, "," );
193                m_exclude = new Pattern[ ptrns.length ];
194                for ( int i = 0; i < ptrns.length; i++ ) {
195                    m_exclude[ i ] = pc.compile( ptrns[ i ] );
196                }
197            } catch ( final MalformedPatternException e ) {
198                throw new PluginException( "Exclude-parameter has a malformed pattern: " + e.getMessage() );
199            }
200        }
201
202        // TODO: Cut-n-paste, refactor
203        s = params.get( PARAM_INCLUDE );
204        if ( s != null ) {
205            try {
206                final PatternCompiler pc = new GlobCompiler();
207                final String[] ptrns = StringUtils.split( s, "," );
208                m_include = new Pattern[ ptrns.length ];
209                for ( int i = 0; i < ptrns.length; i++ ) {
210                    m_include[ i ] = pc.compile( ptrns[ i ] );
211                }
212            } catch ( final MalformedPatternException e ) {
213                throw new PluginException( "Include-parameter has a malformed pattern: " + e.getMessage() );
214            }
215        }
216
217        // LOG.debug( "Requested maximum width is "+m_maxwidth );
218        s = params.get(PARAM_SHOW);
219        if ( s != null ) {
220            if ( s.equalsIgnoreCase( "count" ) ) {
221                m_show = "count";
222            }
223        }
224
225        s = params.get( PARAM_LASTMODIFIED );
226        if ( s != null ) {
227            if ( s.equalsIgnoreCase( "true" ) ) {
228                if ( m_show.equals( "count" ) ) {
229                    m_lastModified = true;
230                } else {
231                    throw new PluginException( "showLastModified=true is only valid if show=count is also specified" );
232                }
233            }
234        }
235
236        initSorter( context, params );
237    }
238
239    /**
240     *  Tells whether the viewer of the context may view a page. The lists of pages are shown to everybody, so they must
241     *  hold only the pages that the viewer may view. A name that is not the name of a page has no ACL to check.
242     *
243     *  @param context The context of the viewer.
244     *  @param pageName The name of the page.
245     *  @return {@code true} if the page does not exist or the viewer has the view permission of the page.
246     */
247    static boolean mayView( final Context context, final String pageName ) {
248        final Engine engine = context.getEngine();
249        final Page page = engine.getManager( PageManager.class ).getPage( pageName );
250        return page == null || engine.getManager( AuthorizationManager.class )
251                                     .checkPermission( context.getWikiSession(), PermissionFactory.getPagePermission( page, "view" ) );
252    }
253
254    /**
255     *  Tells whether a page that does not exist yet is linked from at least one page that the viewer may view. A link
256     *  that is written only inside pages that the viewer may not view says something about the content of those pages.
257     *
258     *  @param context The context of the viewer.
259     *  @param referenceManager The reference manager.
260     *  @param pageName The name of the page that does not exist.
261     *  @return {@code true} if a page that the viewer may view links to it.
262     */
263    static boolean hasViewableReferrer( final Context context, final ReferenceManager referenceManager, final String pageName ) {
264        final Collection< String > referrers = referenceManager.findReferrers( pageName );
265        return referrers != null && referrers.stream().anyMatch( referrer -> mayView( context, referrer ) );
266    }
267
268    protected List< Page > filterWikiPageCollection( final Collection< Page > pages ) {
269        final List< String > pageNames = filterCollection( pages.stream()
270                                                                .map( Page::getName )
271                                                                .collect( Collectors.toList() ) );
272        return pages.stream()
273                    .filter( wikiPage -> pageNames.contains( wikiPage.getName() ) )
274                    .collect( Collectors.toList() );
275    }
276
277    /**
278     *  Filters a collection according to the include and exclude parameters.
279     *
280     *  @param c The collection to filter.
281     *  @return A filtered collection.
282     */
283    protected List< String > filterCollection( final Collection< String > c ) {
284        final ArrayList< String > result = new ArrayList<>();
285        final PatternMatcher pm = new Perl5Matcher();
286        for( final String pageName : c ) {
287            //
288            //  If include parameter exists, then by default we include only those
289            //  pages in it (excluding the ones in the exclude pattern list).
290            //
291            //  include='*' means the same as no include.
292            //
293            boolean includeThis = m_include == null;
294
295            if( m_include != null ) {
296                includeThis = Arrays.stream(m_include).anyMatch(pattern -> pm.matches(pageName, pattern)) ? true : m_include == null;
297            }
298
299            if( m_exclude != null ) {
300                // The inner loop, continue on the next item
301                if (Arrays.stream(m_exclude).anyMatch(pattern -> pm.matches(pageName, pattern))) {
302                    includeThis = false;
303                }
304            }
305
306            if( includeThis ) {
307                result.add( pageName );
308                //  if we want to show the last modified date of the most recently change page, we keep a "high watermark" here:
309                final Page page;
310                if( m_lastModified ) {
311                    page = m_engine.getManager( PageManager.class ).getPage( pageName );
312                    if( page != null ) {
313                        final Date lastModPage = page.getLastModified();
314                        LOG.debug( "lastModified Date of page {} : {}", pageName, m_dateLastModified );
315                        if( lastModPage.after( m_dateLastModified ) ) {
316                            m_dateLastModified = lastModPage;
317                        }
318                    }
319                }
320            }
321        }
322
323        return result;
324    }
325
326    /**
327     *  Filters and sorts a collection according to the include and exclude parameters.
328     *
329     *  @param c The collection to filter.
330     *  @return A filtered and sorted collection.
331     */
332    protected List< String > filterAndSortCollection( final Collection< String > c ) {
333        final List< String > result = filterCollection( c );
334        result.sort( m_sorter );
335        return result;
336    }
337
338    /**
339     *  Makes WikiText from a Collection.
340     *
341     *  @param links Collection to make into WikiText.
342     *  @param separator Separator string to use.
343     *  @param numItems How many items to show.
344     *  @return The WikiText
345     */
346    protected String wikitizeCollection( final Collection< String > links, final String separator, final int numItems ) {
347        if( links == null || links.isEmpty() ) {
348            return "";
349        }
350
351        final StringBuilder output = new StringBuilder();
352
353        final Iterator< String > it = links.iterator();
354        int count = 0;
355
356        //  The output will be B Item[1] A S B Item[2] A S B Item[3] A
357        while( it.hasNext() && ( (count < numItems) || ( numItems == ALL_ITEMS ) ) ) {
358            final String value = it.next();
359            if( count > 0 ) {
360                output.append( m_after );
361                output.append( separator );
362            }
363
364            output.append( m_before );
365
366            // Make a Wiki markup link. See TranslatorReader.
367            output.append( "[" )
368                  .append( m_engine.getManager( RenderingManager.class ).beautifyTitle( value ) )
369                  .append( "|" )
370                  .append( value )
371                  .append( "]" );
372            count++;
373        }
374
375        //  Output final item - if there have been none, no "after" is printed
376        if( count > 0 ) {
377            output.append( m_after );
378        }
379
380        return output.toString();
381    }
382
383    /**
384     *  Makes HTML with common parameters.
385     *
386     *  @param context The WikiContext
387     *  @param wikitext The wikitext to render
388     *  @return HTML
389     *  @since 1.6.4
390     */
391    protected String makeHTML( final Context context, final String wikitext ) {
392        String result = "";
393
394        final RenderingManager mgr = m_engine.getManager( RenderingManager.class );
395
396        try {
397            final MarkupParser parser = mgr.getParser( context, wikitext );
398            parser.addLinkTransmutator( new CutMutator( m_maxwidth ) );
399            parser.enableImageInlining( false );
400
401            final WikiDocument doc = parser.parse();
402            result = mgr.getHTML( context, doc );
403        } catch( final IOException e ) {
404            LOG.error("Failed to convert page data to HTML", e);
405        }
406
407        return result;
408    }
409
410    protected String applyColumnsStyle( final String result ) {
411        if( items > 1 ) {
412            return "<div style=\"columns:" + items + ";" +
413                                "-moz-columns:" + items + ";" +
414                                "-webkit-columns:" + items + ";" + "\">"
415                    + result + "</div>";
416        }
417        return result;
418    }
419
420    /**
421     *  A simple class that just cuts a String to a maximum
422     *  length, adding three dots after the cutpoint.
423     */
424    private static class CutMutator implements StringTransmutator {
425
426        private final int m_length;
427
428        public CutMutator( final int length ) {
429            m_length = length;
430        }
431
432        @Override
433        public String mutate( final Context context, final String text ) {
434            if( text.length() > m_length ) {
435                return text.substring( 0, m_length ) + "...";
436            }
437
438            return text;
439        }
440    }
441
442    /**
443     * Helper method to initialize the comparator for this page.
444     */
445    private void initSorter( final Context context, final Map< String, String > params ) {
446        final String order = params.get( PARAM_SORTORDER );
447        if( order == null || order.isEmpty() ) {
448            // Use the configured comparator
449            m_sorter = context.getEngine().getManager( PageManager.class ).getPageSorter();
450        } else if( order.equalsIgnoreCase( PARAM_SORTORDER_JAVA ) ) {
451            // use Java "natural" ordering
452            m_sorter = new PageSorter( JavaNaturalComparator.DEFAULT_JAVA_COMPARATOR );
453        } else if( order.equalsIgnoreCase( PARAM_SORTORDER_LOCALE ) ) {
454            // use this locale's ordering
455            m_sorter = new PageSorter( LocaleComparator.DEFAULT_LOCALE_COMPARATOR );
456        } else if( order.equalsIgnoreCase( PARAM_SORTORDER_HUMAN ) ) {
457            // use human ordering
458            m_sorter = new PageSorter( HumanComparator.DEFAULT_HUMAN_COMPARATOR );
459        } else {
460            try {
461                final Collator collator = new RuleBasedCollator( order );
462                collator.setStrength( Collator.PRIMARY );
463                m_sorter = new PageSorter( new CollatorComparator( collator ) );
464            } catch( final ParseException pe ) {
465                LOG.info( "Failed to parse requested collator - using default ordering", pe );
466                m_sorter = context.getEngine().getManager( PageManager.class ).getPageSorter();
467            }
468        }
469    }
470
471}