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.providers;
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.Engine;
025import org.apache.wiki.api.core.Page;
026import org.apache.wiki.api.exceptions.NoRequiredPropertyException;
027import org.apache.wiki.api.exceptions.ProviderException;
028import org.apache.wiki.api.providers.PageProvider;
029import org.apache.wiki.api.search.QueryItem;
030import org.apache.wiki.api.search.SearchResult;
031import org.apache.wiki.api.spi.Wiki;
032import org.apache.wiki.cache.CacheInfo;
033import org.apache.wiki.cache.CachingManager;
034import org.apache.wiki.pages.PageManager;
035import org.apache.wiki.parser.MarkupParser;
036import org.apache.wiki.render.RenderingManager;
037import org.apache.wiki.util.ClassUtil;
038import org.apache.wiki.util.Synchronizer;
039import org.apache.wiki.util.TextUtil;
040
041import java.io.IOException;
042import java.util.Collection;
043import java.util.Date;
044import java.util.List;
045import java.util.NoSuchElementException;
046import java.util.Properties;
047import java.util.TreeSet;
048import java.util.concurrent.atomic.AtomicBoolean;
049import java.util.concurrent.atomic.AtomicLong;
050import java.util.concurrent.locks.ReentrantLock;
051
052
053/**
054 *  Provides a caching page provider.  This class rests on top of a real provider class and provides a cache to speed things up.  Only
055 *  if the cache copy of the page text has expired, we fetch it from the provider.
056 *  <p>
057 *  This class does not detect if someone has modified the page externally, not through JSPWiki routines.
058 *  <p>
059 *  Heavily based on ideas by Chris Brooking.
060 *  <p>
061 *  Since 2.10 uses the Ehcache library.
062 *
063 *  @since 1.6.4
064 */
065public class CachingProvider implements PageProvider {
066
067    private static final Logger LOG = LogManager.getLogger( CachingProvider.class );
068
069    private CachingManager cachingManager;
070    private PageProvider provider;
071    private Engine engine;
072
073    private final AtomicBoolean allRequested = new AtomicBoolean();
074    private final AtomicLong pages = new AtomicLong( 0L );
075
076    /**
077     * A lock used to ensure thread safety when accessing shared resources.
078     * This lock provides more flexibility and capabilities than the intrinsic locking mechanism,
079     * such as the ability to attempt to acquire a lock with a timeout, or to interrupt a thread
080     * waiting to acquire a lock.
081     *
082     * @see java.util.concurrent.locks.ReentrantLock
083     */
084    private final ReentrantLock lock = new ReentrantLock();
085
086    /**
087     *  {@inheritDoc}
088     */
089    @Override
090    public void initialize( final Engine engine, final Properties properties ) throws NoRequiredPropertyException, IOException {
091        LOG.debug( "Initializing CachingProvider" );
092
093        // engine is used for getting the search engine
094        this.engine = engine;
095        cachingManager = this.engine.getManager( CachingManager.class );
096        cachingManager.registerListener( CachingManager.CACHE_PAGES, "expired", allRequested );
097
098        //  Find and initialize real provider.
099        final String classname;
100        try {
101            classname = TextUtil.getRequiredProperty( properties, PageManager.PROP_PAGEPROVIDER );
102        } catch( final NoSuchElementException e ) {
103            throw new NoRequiredPropertyException( e.getMessage(), PageManager.PROP_PAGEPROVIDER );
104        }
105
106        try {
107            provider = ClassUtil.buildInstance( "org.apache.wiki.providers", classname );
108            LOG.debug( "Initializing real provider class {}", provider );
109            provider.initialize( engine, properties );
110        } catch( final ReflectiveOperationException e ) {
111            LOG.error( "Unable to instantiate provider class {}", classname, e );
112            throw new IllegalArgumentException( "illegal provider class", e );
113        }
114    }
115
116    private Page getPageInfoFromCache( final String name ) throws ProviderException {
117        // Sanity check; seems to occur sometimes
118        if( name == null ) {
119            return null;
120        }
121        return cachingManager.get( CachingManager.CACHE_PAGES, name, () -> provider.getPageInfo( name, PageProvider.LATEST_VERSION ) );
122    }
123
124
125    /**
126     *  {@inheritDoc}
127     */
128    @Override
129    public boolean pageExists( final String pageName, final int version ) {
130        if( pageName == null ) {
131            return false;
132        }
133
134        final Page p;
135        try {
136            p = getPageInfoFromCache( pageName );
137        } catch( final ProviderException e ) {
138            LOG.info( "Provider failed while trying to check if page exists: {}", pageName );
139            return false;
140        }
141
142        if( p != null ) {
143            final int latestVersion = p.getVersion();
144            if( version == latestVersion || version == LATEST_VERSION ) {
145                return true;
146            }
147
148            return provider.pageExists( pageName, version );
149        }
150
151        try {
152            return getPageInfo( pageName, version ) != null;
153        } catch( final ProviderException e ) {
154            LOG.info( "Provider failed while retrieving {}", pageName );
155        }
156
157        return false;
158    }
159
160    /**
161     *  {@inheritDoc}
162     */
163    @Override
164    public boolean pageExists( final String pageName ) {
165        if( pageName == null ) {
166            return false;
167        }
168
169        final Page p;
170        try {
171            p = getPageInfoFromCache( pageName );
172        } catch( final ProviderException e ) {
173            LOG.info( "Provider failed while trying to check if page exists: {}", pageName );
174            return false;
175        }
176
177        //  A null item means that the page either does not exist, or has not yet been cached; a non-null means that the page does exist.
178        if( p != null ) {
179            return true;
180        }
181
182        //  If we have a list of all pages in memory, then any page not in the cache must be non-existent.
183        if( pages.get() < cachingManager.info( CachingManager.CACHE_PAGES ).getMaxElementsAllowed() ) {
184            return false;
185        }
186
187        //  We could add the page to the cache here as well, but in order to understand whether that is a good thing or not we would
188        //  need to analyze the JSPWiki calling patterns extensively.  Presumably it would be a good thing if pageExists() is called
189        //  many times before the first getPageText() is called, and the whole page is cached.
190        return provider.pageExists( pageName );
191    }
192
193    /**
194     *  {@inheritDoc}
195     */
196    @Override
197    public String getPageText( final String pageName, final int version ) throws ProviderException {
198        if( pageName == null ) {
199            return null;
200        }
201
202        final String result;
203        if( version == PageProvider.LATEST_VERSION ) {
204            result = getTextFromCache( pageName );
205        } else {
206            final Page p = getPageInfoFromCache( pageName );
207
208            //  Or is this the latest version fetched by version number?
209            if( p != null && p.getVersion() == version ) {
210                result = getTextFromCache( pageName );
211            } else {
212                result = provider.getPageText( pageName, version );
213            }
214        }
215
216        return result;
217    }
218
219    private String getTextFromCache( final String pageName ) throws ProviderException {
220        if( pageName == null ) {
221            return null;
222        }
223
224        return cachingManager.get( CachingManager.CACHE_PAGES_TEXT, pageName, () -> {
225            if( pageExists( pageName ) ) {
226                return provider.getPageText( pageName, PageProvider.LATEST_VERSION );
227            }
228            return null;
229        } );
230    }
231
232    /**
233     *  {@inheritDoc}
234     */
235    @Override
236    public void putPageText( final Page page, final String text ) throws ProviderException {
237        Synchronizer.synchronize(lock, () -> {
238            provider.putPageText( page, text );
239            page.setLastModified( new Date() );
240
241            // Refresh caches properly
242            cachingManager.remove( CachingManager.CACHE_PAGES, page.getName() );
243            cachingManager.remove( CachingManager.CACHE_PAGES_TEXT, page.getName() );
244            cachingManager.remove( CachingManager.CACHE_PAGES_HISTORY, page.getName() );
245
246            getPageInfoFromCache( page.getName() );
247        });
248        pages.incrementAndGet();
249    }
250
251    /**
252     *  {@inheritDoc}
253     */
254    @Override
255    public Collection< Page > getAllPages() throws ProviderException {
256        final Collection< Page > all;
257        if ( !allRequested.get() ) {
258            all = provider.getAllPages();
259            // Make sure that all pages are in the cache.
260            Synchronizer.synchronize(lock, () -> {
261                for( final Page p : all ) {
262                    cachingManager.put( CachingManager.CACHE_PAGES,  p.getName(), p );
263                }
264                allRequested.set( true );
265            });
266            pages.set( all.size() );
267        } else {
268            final List< String > keys = cachingManager.keys( CachingManager.CACHE_PAGES );
269            all = new TreeSet<>();
270            for( final String key : keys ) {
271                final Page cachedPage = cachingManager.get( CachingManager.CACHE_PAGES, key, () -> null );
272                if( cachedPage != null ) {
273                    all.add( cachedPage );
274                }
275            }
276        }
277
278        if( cachingManager.enabled( CachingManager.CACHE_PAGES )
279                && pages.get() >= cachingManager.info( CachingManager.CACHE_PAGES ).getMaxElementsAllowed() ) {
280            LOG.warn( "seems {} can't hold all pages from your page repository, " +
281                    "so we're delegating on the underlying provider instead. Please consider increasing " +
282                    "your cache sizes on the ehcache configuration file to avoid this behaviour", CachingManager.CACHE_PAGES );
283            return provider.getAllPages();
284        }
285
286        return all;
287    }
288
289    /**
290     *  {@inheritDoc}
291     */
292    @Override
293    public Collection< Page > getAllChangedSince( final Date date ) {
294        return provider.getAllChangedSince( date );
295    }
296
297    /**
298     *  {@inheritDoc}
299     */
300    @Override
301    public int getPageCount() throws ProviderException {
302        return provider.getPageCount();
303    }
304
305    /**
306     *  {@inheritDoc}
307     */
308    @Override
309    public Collection< SearchResult > findPages( final QueryItem[] query ) {
310        //  If the provider is a fast searcher, then just pass this request through.
311        return provider.findPages( query );
312        // FIXME: Does not implement fast searching
313    }
314
315    //  FIXME: Kludge: make sure that the page is also parsed and it gets all the necessary variables.
316    private void refreshMetadata( final Page page ) {
317        if( page != null && !page.hasMetadata() ) {
318            final RenderingManager mgr = engine.getManager( RenderingManager.class );
319            try {
320                final String data = provider.getPageText( page.getName(), page.getVersion() );
321                final Context ctx = Wiki.context().create( engine, page );
322                final MarkupParser parser = mgr.getParser( ctx, data );
323
324                parser.parse();
325            } catch( final Exception ex ) {
326                LOG.debug( "Failed to retrieve variables for wikipage {}", page );
327            }
328        }
329    }
330
331    /**
332     *  {@inheritDoc}
333     */
334    @Override
335    public Page getPageInfo( final String pageName, final int version ) throws ProviderException {
336        final Page page;
337        final Page cached = getPageInfoFromCache( pageName );
338        final int latestcached = ( cached != null ) ? cached.getVersion() : Integer.MIN_VALUE;
339        if( version == PageProvider.LATEST_VERSION || version == latestcached ) {
340            page = cached;
341        } else {
342            // We do not cache old versions.
343            page = provider.getPageInfo( pageName, version );
344        }
345        refreshMetadata( page );
346        return page;
347    }
348
349    /**
350     *  {@inheritDoc}
351     */
352    @Override
353    public List< Page > getVersionHistory( final String pageName) throws ProviderException {
354        if( pageName == null ) {
355            return null;
356        }
357        return cachingManager.get( CachingManager.CACHE_PAGES_HISTORY, pageName, () -> provider.getVersionHistory( pageName ) );
358    }
359
360    /**
361     * Gets the provider class name, and cache statistics (misscount and hitcount of page cache and history cache).
362     *
363     * @return A plain string with all the above-mentioned values.
364     */
365    @Override
366    public String getProviderInfo() {
367        return Synchronizer.synchronize(lock, () -> {
368            final CacheInfo pageCacheInfo = cachingManager.info( CachingManager.CACHE_PAGES );
369            final CacheInfo pageHistoryCacheInfo = cachingManager.info( CachingManager.CACHE_PAGES_HISTORY );
370            return "Real provider: " + provider.getClass().getName()+
371                    ". Page cache hits: " + pageCacheInfo.getHits() +
372                    ". Page cache misses: " + pageCacheInfo.getMisses() +
373                    ". History cache hits: " + pageHistoryCacheInfo.getHits() +
374                    ". History cache misses: " + pageHistoryCacheInfo.getMisses();
375        });
376    }
377
378    /**
379     *  {@inheritDoc}
380     */
381    @Override
382    public void deleteVersion( final String pageName, final int version ) throws ProviderException {
383        //  Luckily, this is such a rare operation it is okay to synchronize against the whole thing.
384        Synchronizer.synchronize(lock, (Synchronizer.ThrowingRunnable<ProviderException>) () -> {
385            final Page cached = getPageInfoFromCache( pageName );
386            final int latestcached = ( cached != null ) ? cached.getVersion() : Integer.MIN_VALUE;
387
388            //  If we have this version cached, remove from cache.
389            if( version == PageProvider.LATEST_VERSION || version == latestcached ) {
390                cachingManager.remove( CachingManager.CACHE_PAGES, pageName );
391                cachingManager.remove( CachingManager.CACHE_PAGES_TEXT, pageName );
392            }
393
394            provider.deleteVersion( pageName, version );
395            cachingManager.remove( CachingManager.CACHE_PAGES_HISTORY, pageName );
396        });
397        if( version == PageProvider.LATEST_VERSION ) {
398            pages.decrementAndGet();
399        }
400    }
401
402    /**
403     *  {@inheritDoc}
404     */
405    @Override
406    public void deletePage( final String pageName ) throws ProviderException {
407        //  See note in deleteVersion().
408        Synchronizer.synchronize(lock, () -> {
409            cachingManager.put( CachingManager.CACHE_PAGES, pageName, null );
410            cachingManager.put( CachingManager.CACHE_PAGES_TEXT, pageName, null );
411            cachingManager.put( CachingManager.CACHE_PAGES_HISTORY, pageName, null );
412            provider.deletePage( pageName );
413        });
414        pages.decrementAndGet();
415    }
416
417    /**
418     *  {@inheritDoc}
419     */
420    @Override
421    public void movePage( final String from, final String to ) throws ProviderException {
422        provider.movePage( from, to );
423        Synchronizer.synchronize(lock, () -> {
424            // Clear any cached version of the old page and new page
425            cachingManager.remove( CachingManager.CACHE_PAGES, from );
426            cachingManager.remove( CachingManager.CACHE_PAGES_TEXT, from );
427            cachingManager.remove( CachingManager.CACHE_PAGES_HISTORY, from );
428            LOG.debug( "Removing to page {} from cache", to );
429            cachingManager.remove( CachingManager.CACHE_PAGES, to );
430            cachingManager.remove( CachingManager.CACHE_PAGES_TEXT, to );
431            cachingManager.remove( CachingManager.CACHE_PAGES_HISTORY, to );
432        });
433    }
434
435    /**
436     *  Returns the actual used provider.
437     *
438     *  @since 2.0
439     *  @return The real provider.
440     */
441    public PageProvider getRealProvider() {
442        return provider;
443    }
444
445}