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.commons.lang3.math.NumberUtils;
023import org.apache.logging.log4j.LogManager;
024import org.apache.logging.log4j.Logger;
025import org.apache.oro.text.GlobCompiler;
026import org.apache.oro.text.regex.MalformedPatternException;
027import org.apache.oro.text.regex.Pattern;
028import org.apache.oro.text.regex.PatternCompiler;
029import org.apache.oro.text.regex.PatternMatcher;
030import org.apache.oro.text.regex.Perl5Matcher;
031import org.apache.wiki.WikiBackgroundThread;
032import org.apache.wiki.api.core.Context;
033import org.apache.wiki.api.core.ContextEnum;
034import org.apache.wiki.api.core.Engine;
035import org.apache.wiki.api.core.Page;
036import org.apache.wiki.api.exceptions.PluginException;
037import org.apache.wiki.api.plugin.InitializablePlugin;
038import org.apache.wiki.api.plugin.Plugin;
039import org.apache.wiki.event.WikiEngineEvent;
040import org.apache.wiki.event.WikiEvent;
041import org.apache.wiki.event.WikiEventListener;
042import org.apache.wiki.event.WikiPageEvent;
043import org.apache.wiki.event.WikiPageRenameEvent;
044import org.apache.wiki.references.ReferenceManager;
045import org.apache.wiki.render.RenderingManager;
046import org.apache.wiki.util.Synchronizer;
047import org.apache.wiki.util.TextUtil;
048
049import java.io.File;
050import java.io.IOException;
051import java.io.InputStream;
052import java.io.OutputStream;
053import java.nio.file.Files;
054import java.text.MessageFormat;
055import java.util.Collection;
056import java.util.Comparator;
057import java.util.HashSet;
058import java.util.Iterator;
059import java.util.Locale;
060import java.util.Map;
061import java.util.Map.Entry;
062import java.util.Properties;
063import java.util.ResourceBundle;
064import java.util.TreeMap;
065import java.util.concurrent.atomic.AtomicBoolean;
066import java.util.concurrent.atomic.AtomicInteger;
067import java.util.concurrent.atomic.AtomicReference;
068import java.util.concurrent.locks.ReentrantLock;
069
070
071/**
072 * This plugin counts the number of times a page has been viewed.<br/>
073 * Parameters:
074 * <ul>
075 * <li>count=yes|no</li>
076 * <li>show=none|count|list</li>
077 * <li>entries=maximum number of list entries to be returned</li>
078 * <li>min=minimum page count to be listed</li>
079 * <li>max=maximum page count to be listed</li>
080 * <li>sort=name|count</li>
081 * </ul>
082 * Default values:<br/>
083 * <code>show=none  sort=name</code>
084 * 
085 * @since 2.8
086 */
087public class PageViewPlugin extends AbstractReferralPlugin implements Plugin, InitializablePlugin {
088
089    private static final Logger LOG = LogManager.getLogger( PageViewPlugin.class );
090
091    /** The page view manager. */
092    private static PageViewManager c_singleton;
093
094    /** Constant for the 'count' parameter / value. */
095    private static final String PARAM_COUNT = "count";
096
097    /** Name of the 'entries' parameter. */
098    private static final String PARAM_MAX_ENTRIES = "entries";
099
100    /** Name of the 'max' parameter. */
101    private static final String PARAM_MAX_COUNT = "max";
102
103    /** Name of the 'min' parameter. */
104    private static final String PARAM_MIN_COUNT = "min";
105
106    /** Name of the 'refer' parameter. */
107    private static final String PARAM_REFER = "refer";
108
109    /** Name of the 'sort' parameter. */
110    private static final String PARAM_SORT = "sort";
111
112    /** Constant for the 'none' parameter value. */
113    private static final String STR_NONE = "none";
114
115    /** Constant for the 'list' parameter value. */
116    private static final String STR_LIST = "list";
117
118    /** Constant for the 'yes' parameter value. */
119    private static final String STR_YES = "yes";
120
121    /** Constant for empty string. */
122    private static final String STR_EMPTY = "";
123
124    /** Constant for Wiki markup separator. */
125    private static final String STR_SEPARATOR = "----";
126
127    /** Constant for comma-separated list separator. */
128    private static final String STR_COMMA = ",";
129
130    /** Constant for no-op glob expression. */
131    private static final String STR_GLOBSTAR = "*";
132
133    /** Constant for file storage. */
134    private static final String COUNTER_PAGE = "PageCount.txt";
135
136    /** Constant for storage interval in seconds. */
137    private static final int STORAGE_INTERVAL = 60;
138
139    @Override
140    public String getDisplayName(Locale locale) {
141        final ResourceBundle rb = ResourceBundle.getBundle(PluginManager.PLUGIN_I18N_RESOURCE, locale);
142        return rb.getString(this.getClass().getSimpleName());
143    }
144    
145    /**
146     * A lock used to ensure thread safety when accessing shared resources.
147     * This lock provides more flexibility and capabilities than the intrinsic locking mechanism,
148     * such as the ability to attempt to acquire a lock with a timeout, or to interrupt a thread
149     * waiting to acquire a lock.
150     *
151     * @see java.util.concurrent.locks.ReentrantLock
152     */
153    private final ReentrantLock lock = new ReentrantLock();
154
155    /**
156     * Initialize the PageViewPlugin and its singleton.
157     * 
158     * @param engine The wiki engine.
159     */
160    @Override
161    public void initialize( final Engine engine ) {
162        LOG.info( "initializing PageViewPlugin" );
163        Synchronizer.synchronize( lock, () -> {
164            if( c_singleton == null ) {
165                c_singleton = new PageViewManager();
166            }
167            c_singleton.initialize( engine );
168        } );
169    }
170
171    /**
172     * Cleanup the singleton reference.
173     */
174    private void cleanup() {
175        LOG.info( "cleaning up PageView Manager" );
176        c_singleton = null;
177    }
178
179    /**
180     *  {@inheritDoc}
181     */
182    @Override
183    public String execute( final Context context, final Map< String, String > params ) throws PluginException {
184        final PageViewManager manager = c_singleton;
185        String result = STR_EMPTY;
186
187        if( manager != null ) {
188            result = manager.execute( context, params );
189        }
190
191        return result;
192    }
193
194    /**
195     * Page view manager, handling all storage.
196     */
197    public final class PageViewManager implements WikiEventListener {
198        /** Are we initialized? */
199        private boolean m_initialized;
200
201        /** The page counters. */
202        private Map<String, Counter> m_counters;
203
204        /** The page counters in storage format. */
205        private Properties m_storage;
206
207        /** Are all changes stored? */
208        private boolean m_dirty;
209
210        /** The page count storage background thread. */
211        private Thread m_pageCountSaveThread;
212
213        /** The work directory. */
214        private String m_workDir;
215
216        /** Comparator for descending sort on page count. */
217        private final Comparator< Object > m_compareCountDescending = ( o1, o2 ) -> {
218            final int v1 = getCount( o1 );
219            final int v2 = getCount( o2 );
220            return ( v1 == v2 ) ? ( ( String )o1 ).compareTo( ( String )o2 ) : ( v1 < v2 ) ? 1 : -1;
221        };
222
223        /**
224         * Initialize the page view manager.
225         * 
226         * @param engine The wiki engine.
227         */
228        public void initialize( final Engine engine ) {
229            Synchronizer.synchronize( lock, () -> {
230                LOG.info( "initializing PageView Manager" );
231                m_workDir = engine.getWorkDir();
232                engine.addWikiEventListener( this );
233                if( m_counters == null ) {
234                    // Load the counters into a collection
235                    m_storage = new Properties();
236                    m_counters = new TreeMap<>();
237
238                    loadCounters();
239                }
240
241                // backup counters every 5 minutes
242                if( m_pageCountSaveThread == null ) {
243                    m_pageCountSaveThread = new CounterSaveThread( engine, 5 * STORAGE_INTERVAL, this );
244                    m_pageCountSaveThread.start();
245                }
246
247                m_initialized = true;
248            } );
249        }
250
251        /**
252         * Handle the shutdown event via the page counter thread.
253         */
254        private void handleShutdown() {
255            Synchronizer.synchronize(lock, () -> {
256                LOG.info( "handleShutdown: The counter store thread was shut down." );
257
258                cleanup();
259
260                if( m_counters != null ) {
261
262                    m_dirty = true;
263                    storeCounters();
264
265                    m_counters.clear();
266                    m_counters = null;
267
268                    m_storage.clear();
269                    m_storage = null;
270                }
271
272                m_initialized = false;
273
274                m_pageCountSaveThread = null;
275            });
276        }
277
278        /**
279         * Inspect wiki events for shutdown.
280         * 
281         * @param event The wiki event to inspect.
282         */
283        @Override
284        public void actionPerformed( final WikiEvent event ) {
285            if( event instanceof WikiEngineEvent ) {
286                if( event.getType() == WikiEngineEvent.SHUTDOWN ) {
287                    LOG.info( "Detected wiki engine shutdown" );
288                    handleShutdown();
289                }
290            } else if( ( event instanceof WikiPageRenameEvent ) && ( event.getType() == WikiPageRenameEvent.PAGE_RENAMED ) ) {
291                final String oldPageName = ( ( WikiPageRenameEvent )event ).getOldPageName();
292                final String newPageName = ( ( WikiPageRenameEvent )event ).getNewPageName();
293                final Counter oldCounter = m_counters.get( oldPageName );
294                if( oldCounter != null ) {
295                    m_storage.remove( oldPageName );
296                    m_counters.put( newPageName, oldCounter );
297                    m_storage.setProperty( newPageName, oldCounter.toString() );
298                    m_counters.remove( oldPageName );
299                    m_dirty = true;
300                }
301            } else if( ( event instanceof WikiPageEvent ) && ( event.getType() == WikiPageEvent.PAGE_DELETED ) ) {
302                final String pageName = ( ( WikiPageEvent )event ).getPageName();
303                m_storage.remove( pageName );
304                m_counters.remove( pageName );
305            }
306        }
307
308        /**
309         * Count a page hit, present a pages' counter or output a list of page counts.
310         * 
311         * @param context the wiki context
312         * @param params the plugin parameters
313         * @return String Wiki page snippet
314         * @throws PluginException Malformed pattern parameter.
315         */
316        public String execute( final Context context, final Map< String, String > params ) throws PluginException {
317            final Engine engine = context.getEngine();
318            final Page page = context.getPage();
319            final AtomicReference<String> atomicResult = new AtomicReference<>(STR_EMPTY);
320            final AtomicReference<PluginException> pluginExceptionRef = new AtomicReference<>();
321
322            if( page != null ) {
323                // get parameters
324                final String pagename = page.getName();
325                String count = params.get( PARAM_COUNT );
326                final String show = params.get( PARAM_SHOW );
327                final AtomicInteger atomicEntries = new AtomicInteger(TextUtil.parseIntParameter(params.get(PARAM_MAX_ENTRIES), Integer.MAX_VALUE));
328                final int max = TextUtil.parseIntParameter( params.get( PARAM_MAX_COUNT ), Integer.MAX_VALUE );
329                final int min = TextUtil.parseIntParameter( params.get( PARAM_MIN_COUNT ), Integer.MIN_VALUE );
330                final String sort = params.get( PARAM_SORT );
331                final String body = params.get( DefaultPluginManager.PARAM_BODY );
332                final Pattern[] exclude = compileGlobs( PARAM_EXCLUDE, params.get( PARAM_EXCLUDE ) );
333                final Pattern[] include = compileGlobs( PARAM_INCLUDE, params.get( PARAM_INCLUDE ) );
334                final Pattern[] refer = compileGlobs( PARAM_REFER, params.get( PARAM_REFER ) );
335                final PatternMatcher matcher = (null != exclude || null != include || null != refer) ? new Perl5Matcher() : null;
336                final AtomicBoolean atomicIncrement = new AtomicBoolean(false);
337
338                // increment counter?
339                if( STR_YES.equals( count ) ) {
340                    atomicIncrement.set(true);
341                } else {
342                    count = null;
343                }
344
345                // default increment counter?
346                if( ( show == null || STR_NONE.equals( show ) ) && count == null ) {
347                    atomicIncrement.set(true);
348                }
349
350                // filter on referring pages?
351                final AtomicReference<Collection<String>> atomicReferrers = new AtomicReference<>(null);
352
353                if( refer != null ) {
354                    final ReferenceManager refManager = engine.getManager( ReferenceManager.class );
355                    for( final String name : refManager.findCreated() ) {
356                        boolean use = false;
357                        for( int n = 0; !use && n < refer.length; n++ ) {
358                            use = matcher.matches( name, refer[ n ] );
359                        }
360
361                        if( use ) {
362                            final Collection< String > refs = engine.getManager( ReferenceManager.class ).findReferrers( name );
363                            if( refs != null && !refs.isEmpty() ) {
364                                if (atomicReferrers.get() == null) {
365                                    atomicReferrers.set(new HashSet<>());
366                                }
367                                atomicReferrers.get().addAll(refs);
368                            }
369                        }
370                    }
371                }
372
373                Synchronizer.synchronize( lock, () -> {
374                    try {
375
376                        Counter counter = m_counters.get( pagename );
377
378                        // only count in view mode, keep storage values in sync
379                        if( atomicIncrement.get() && ContextEnum.PAGE_VIEW.getRequestContext().equalsIgnoreCase( context.getRequestContext() ) ) {
380                            if( counter == null ) {
381                                counter = new Counter();
382                                m_counters.put( pagename, counter );
383                            }
384                            counter.increment();
385                            m_storage.setProperty( pagename, counter.toString() );
386                            m_dirty = true;
387                        }
388
389                        if( show == null || STR_NONE.equals( show ) ) {
390                            // nothing to show
391
392                        } else if( PARAM_COUNT.equals( show ) ) {
393                            // show page count
394                            if( counter == null ) {
395                                counter = new Counter();
396                                m_counters.put( pagename, counter );
397                                m_storage.setProperty( pagename, counter.toString() );
398                                m_dirty = true;
399                            }
400                            atomicResult.set(counter.toString());
401
402                        } else if( body != null && 0 < body.length() && STR_LIST.equals( show ) ) {
403                            // show list of counts
404                            String header = STR_EMPTY;
405                            String line = body;
406                            String footer = STR_EMPTY;
407                            int start = body.indexOf( STR_SEPARATOR );
408
409                            // split body into header, line, footer on ---- separator
410                            if( 0 < start ) {
411                                header = body.substring( 0, start );
412                                start = skipWhitespace( start + STR_SEPARATOR.length(), body );
413                                int end = body.indexOf( STR_SEPARATOR, start );
414                                if( start >= end ) {
415                                    line = body.substring( start );
416                                } else {
417                                    line = body.substring( start, end );
418                                    end = skipWhitespace( end + STR_SEPARATOR.length(), body );
419                                    footer = body.substring( end );
420                                }
421                            }
422
423                            // sort on name or count?
424                            Map< String, Counter > sorted = m_counters;
425                            if( PARAM_COUNT.equals( sort ) ) {
426                                sorted = new TreeMap<>( m_compareCountDescending );
427                                sorted.putAll( m_counters );
428                            }
429
430                            // build a messagebuffer with the list in wiki markup
431                            final StringBuffer buf = new StringBuffer( header );
432                            final MessageFormat fmt = new MessageFormat( line );
433                            final Object[] args = new Object[] { pagename, STR_EMPTY, STR_EMPTY };
434                            final Iterator< Entry< String, Counter > > iter = sorted.entrySet().iterator();
435
436                            while( 0 < atomicEntries.get() && iter.hasNext() ) {
437                                final Entry< String, Counter > entry = iter.next();
438                                final String name = entry.getKey();
439
440                                // check minimum/maximum count
441                                final int value = entry.getValue().getValue();
442                                boolean use = min <= value && value <= max && mayView( context, name );
443
444                                // did we specify a refer-to page?
445                                if( use && atomicReferrers.get() != null ) {
446                                    use = atomicReferrers.get().contains( name );
447                                }
448
449                                // did we specify what pages to include?
450                                if( use && include != null ) {
451                                    use = false;
452
453                                    for( int n = 0; !use && n < include.length; n++ ) {
454                                        use = matcher.matches( name, include[ n ] );
455                                    }
456                                }
457
458                                // did we specify what pages to exclude?
459                                if( use && null != exclude ) {
460                                    for( int n = 0; use && n < exclude.length; n++ ) {
461                                        use = !matcher.matches( name, exclude[ n ] );
462                                    }
463                                }
464
465                                if( use ) {
466                                    args[ 1 ] = engine.getManager( RenderingManager.class ).beautifyTitle( name );
467                                    args[ 2 ] = entry.getValue();
468
469                                    fmt.format( args, buf, null );
470
471                                    atomicEntries.decrementAndGet();
472                                }
473                            }
474                            buf.append( footer );
475
476                            // let the engine render the list
477                            atomicResult.set(engine.getManager(RenderingManager.class).textToHTML(context, buf.toString()));
478                        }
479                    } catch (Exception e) {
480                        if (e instanceof PluginException) {
481                            pluginExceptionRef.set(new PluginException(e.getMessage()));
482                        }
483                    }
484                } );
485            }
486
487            if (pluginExceptionRef.get() != null) {
488                throw pluginExceptionRef.get();
489            }
490
491            return atomicResult.get();
492        }
493
494        /**
495         * Compile regexp parameter.
496         * 
497         * @param name The name of the parameter.
498         * @param value The parameter value.
499         * @return Pattern[] The compiled patterns, or <code>null</code>.
500         * @throws PluginException On malformed patterns.
501         */
502        private Pattern[] compileGlobs( final String name, final String value ) throws PluginException {
503            Pattern[] result = null;
504            if( value != null && 0 < value.length() && !STR_GLOBSTAR.equals( value ) ) {
505                try {
506                    final PatternCompiler pc = new GlobCompiler();
507                    final String[] ptrns = StringUtils.split( value, STR_COMMA );
508                    result = new Pattern[ ptrns.length ];
509
510                    for( int n = 0; n < ptrns.length; n++ ) {
511                        result[ n ] = pc.compile( ptrns[ n ] );
512                    }
513                } catch( final MalformedPatternException e ) {
514                    throw new PluginException( "Parameter " + name + " has a malformed pattern: " + e.getMessage() );
515                }
516            }
517
518            return result;
519        }
520
521        /**
522         * Adjust offset skipping whitespace.
523         * 
524         * @param offset The offset in value to adjust.
525         * @param value String in which offset points.
526         * @return int Adjusted offset into value.
527         */
528        private int skipWhitespace( int offset, final String value ) {
529            while( Character.isWhitespace( value.charAt( offset ) ) ) {
530                offset++;
531            }
532            return offset;
533        }
534
535        /**
536         * Retrieve a page count.
537         * 
538         * @return int The page count for the given key.
539         * @param key the key for the Counter
540         */
541        int getCount( final Object key )
542        {
543            return m_counters.get( key ).getValue();
544        }
545
546        /**
547         * Load the page view counters from file.
548         */
549        private void loadCounters() {
550            if( m_counters != null && m_storage != null ) {
551                LOG.info( "Loading counters." );
552                Synchronizer.synchronize( lock, () -> {
553                    try( final InputStream fis = Files.newInputStream( new File( m_workDir, COUNTER_PAGE ).toPath() ) ) {
554                        m_storage.load( fis );
555                    } catch( final IOException ioe ) {
556                        LOG.debug( "Can't load page counter store: " + ioe.getMessage() + " , will create a new one!" );
557                    }
558
559                    // Copy the collection into a sorted map
560                    for( final Entry< ?, ? > entry : m_storage.entrySet() ) {
561                        m_counters.put( ( String )entry.getKey(), new Counter( ( String )entry.getValue() ) );
562                    }
563
564                    LOG.info( "Loaded " + m_counters.size() + " counter values." );
565                } );
566            }
567        }
568
569        /**
570         * Save the page view counters to file.
571         */
572        void storeCounters() {
573            if( m_counters != null && m_storage != null && m_dirty ) {
574                LOG.info( "Storing " + m_counters.size() + " counter values." );
575                Synchronizer.synchronize( lock, () -> {
576                    // Write out the collection of counters
577                    try( final OutputStream fos = Files.newOutputStream( new File( m_workDir, COUNTER_PAGE ).toPath() ) ) {
578                        m_storage.store( fos, "\n# The number of times each page has been viewed.\n# Do not modify.\n" );
579                        fos.flush();
580
581                        m_dirty = false;
582                    } catch( final IOException ioe ) {
583                        LOG.error( "Couldn't store counters values: " + ioe.getMessage() );
584                    }
585                } );
586            }
587        }
588
589        /**
590         * Is the given thread still current?
591         *
592         * @param thrd thread that can be the current background thread.
593         * @return boolean <code>true</code> if the thread is still the current background thread.
594         */
595        private boolean isRunning( final Thread thrd )
596        {
597            return Synchronizer.synchronize( lock, () -> m_initialized && thrd == m_pageCountSaveThread );
598        }
599
600    }
601
602    /** Counter for page hits collection. */
603    private static final class Counter {
604
605        /** The count value. */
606        private int m_count;
607
608        /**
609         * Create a new counter.
610         */
611        public Counter() {
612        }
613
614        /**
615         * Create and initialize a new counter.
616         * 
617         * @param value Count value.
618         */
619        public Counter( final String value )
620        {
621            setValue( value );
622        }
623
624        /**
625         * Increment counter.
626         */
627        public void increment()
628        {
629            m_count++;
630        }
631
632        /**
633         * Get the count value.
634         * 
635         * @return int
636         */
637        public int getValue()
638        {
639            return m_count;
640        }
641
642        /**
643         * Set the count value.
644         * 
645         * @param value String representation of the count.
646         */
647        public void setValue( final String value )
648        {
649            m_count = NumberUtils.toInt( value );
650        }
651
652        /**
653         * @return String representation of the count.
654         */
655        @Override
656        public String toString()
657        {
658            return String.valueOf( m_count );
659        }
660
661    }
662
663    /**
664     * Background thread storing the page counters.
665     */
666    static final class CounterSaveThread extends WikiBackgroundThread {
667
668        /** The page view manager. */
669        private final PageViewManager m_manager;
670
671        /**
672         * Create a wiki background thread to store the page counters.
673         * 
674         * @param engine The wiki engine.
675         * @param interval Delay in seconds between saves.
676         * @param pageViewManager page view manager.
677         */
678        public CounterSaveThread( final Engine engine, final int interval, final PageViewManager pageViewManager ) {
679            super( engine, interval );
680            if( pageViewManager == null ) {
681                throw new IllegalArgumentException( "Manager cannot be null" );
682            }
683
684            m_manager = pageViewManager;
685        }
686
687        /**
688         * Save the page counters to file.
689         */
690        @Override
691        public void backgroundTask() {
692            if( m_manager.isRunning( this ) ) {
693                m_manager.storeCounters();
694            }
695        }
696    }
697}