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}