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.Attachment;
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.AttachmentProvider;
029import org.apache.wiki.api.providers.PageProvider;
030import org.apache.wiki.api.providers.WikiProvider;
031import org.apache.wiki.api.search.QueryItem;
032import org.apache.wiki.attachment.AttachmentManager;
033import org.apache.wiki.cache.CacheInfo;
034import org.apache.wiki.cache.CachingManager;
035import org.apache.wiki.util.ClassUtil;
036import org.apache.wiki.util.Synchronizer;
037import org.apache.wiki.util.TextUtil;
038
039import java.io.IOException;
040import java.io.InputStream;
041import java.util.ArrayList;
042import java.util.Collection;
043import java.util.Collections;
044import java.util.Date;
045import java.util.List;
046import java.util.NoSuchElementException;
047import java.util.Properties;
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 attachment provider.  This class rests on top of a real provider class and provides a cache to speed things up.
055 * Only the Attachment objects are cached; the actual attachment contents are fetched always from the provider.
056 *
057 *  @since 2.1.64.
058 */
059public class CachingAttachmentProvider implements AttachmentProvider {
060
061    private static final Logger LOG = LogManager.getLogger( CachingAttachmentProvider.class );
062
063    private AttachmentProvider provider;
064    private CachingManager cachingManager;
065    private final AtomicBoolean allRequested = new AtomicBoolean();
066    private final AtomicLong attachments = new AtomicLong( 0L );
067
068    /**
069     * A lock used to ensure thread safety when accessing shared resources.
070     * This lock provides more flexibility and capabilities than the intrinsic locking mechanism,
071     * such as the ability to attempt to acquire a lock with a timeout, or to interrupt a thread
072     * waiting to acquire a lock.
073     *
074     * @see java.util.concurrent.locks.ReentrantLock
075     */
076    private final ReentrantLock lock = new ReentrantLock();
077
078    /**
079     * {@inheritDoc}
080     */
081    @Override
082    public void initialize( final Engine engine, final Properties properties ) throws NoRequiredPropertyException, IOException {
083        LOG.info( "Initing CachingAttachmentProvider" );
084        cachingManager = engine.getManager( CachingManager.class );
085        cachingManager.registerListener( CachingManager.CACHE_ATTACHMENTS, "expired", allRequested );
086
087        // Find and initialize real provider.
088        final String classname;
089        try {
090            classname = TextUtil.getRequiredProperty( properties, AttachmentManager.PROP_PROVIDER, AttachmentManager.PROP_PROVIDER_DEPRECATED );
091        } catch( final NoSuchElementException e ) {
092            throw new NoRequiredPropertyException( e.getMessage(), AttachmentManager.PROP_PROVIDER );
093        }
094
095        try {
096            provider = ClassUtil.buildInstance( "org.apache.wiki.providers", classname );
097            LOG.debug( "Initializing real provider class {}", provider );
098            provider.initialize( engine, properties );
099        } catch( final ReflectiveOperationException e ) {
100            LOG.error( "Unable to instantiate provider class {}", classname, e );
101            throw new IllegalArgumentException( "illegal provider class", e );
102        }
103    }
104
105    /**
106     * {@inheritDoc}
107     */
108    @Override
109    public void putAttachmentData( final Attachment att, final InputStream data ) throws ProviderException, IOException {
110        provider.putAttachmentData( att, data );
111        cachingManager.remove( CachingManager.CACHE_ATTACHMENTS_COLLECTION, att.getParentName() );
112        att.setLastModified( new Date() );
113        cachingManager.put( CachingManager.CACHE_ATTACHMENTS, att.getName(), att );
114        attachments.incrementAndGet();
115    }
116
117    /**
118     * {@inheritDoc}
119     */
120    @Override
121    public InputStream getAttachmentData( final Attachment att ) throws ProviderException, IOException {
122        return provider.getAttachmentData( att );
123    }
124
125    /**
126     * {@inheritDoc}
127     */
128    @Override
129    public List< Attachment > listAttachments( final Page page ) throws ProviderException {
130        LOG.debug( "Listing attachments for {}", page );
131        final List< Attachment > atts = cachingManager.get( CachingManager.CACHE_ATTACHMENTS_COLLECTION, page.getName(),
132                                                            () -> provider.listAttachments( page ) );
133        return cloneCollection( atts );
134    }
135
136    private < T > List< T > cloneCollection( final Collection< T > c ) {
137        return c != null ? new ArrayList<>( c ) : Collections.emptyList();
138    }
139
140    /**
141     * {@inheritDoc}
142     */
143    @Override
144    public Collection< Attachment > findAttachments( final QueryItem[] query ) {
145        return provider.findAttachments( query );
146    }
147
148    /**
149     * {@inheritDoc}
150     */
151    @Override
152    public List< Attachment > listAllChanged( final Date timestamp ) throws ProviderException {
153        final List< Attachment > all;
154        if ( !allRequested.get() ) {
155            all = provider.listAllChanged( timestamp );
156
157            // Make sure that all attachments are in the cache.
158            Synchronizer.synchronize(lock, () -> {
159                for( final Attachment att : all ) {
160                    cachingManager.put( CachingManager.CACHE_ATTACHMENTS, att.getName(), att );
161                }
162                if( timestamp.getTime() == 0L ) { // all attachments requested
163                    allRequested.set( true );
164                    attachments.set( all.size() );
165                }
166            });
167        } else {
168            final List< String > keys = cachingManager.keys( CachingManager.CACHE_ATTACHMENTS );
169            all = new ArrayList<>();
170            for( final String key : keys) {
171                final Attachment cachedAttachment = cachingManager.get( CachingManager.CACHE_ATTACHMENTS, key, () -> null );
172                if( cachedAttachment != null ) {
173                    all.add( cachedAttachment );
174                }
175            }
176        }
177
178        if( cachingManager.enabled( CachingManager.CACHE_ATTACHMENTS )
179                && attachments.get() >= cachingManager.info( CachingManager.CACHE_ATTACHMENTS ).getMaxElementsAllowed() ) {
180            LOG.warn( "seems {} can't hold all attachments from your page repository, " +
181                    "so we're delegating on the underlying provider instead. Please consider increasing " +
182                    "your cache sizes on the ehcache configuration file to avoid this behaviour", CachingManager.CACHE_ATTACHMENTS );
183            return provider.listAllChanged( timestamp );
184        }
185
186        return all;
187    }
188
189    /**
190     *  Simply goes through the collection and attempts to locate the
191     *  given attachment of that name.
192     *
193     *  @return null, if no such attachment was in this collection.
194     */
195    private Attachment findAttachmentFromCollection( final Collection< Attachment > c, final String name ) {
196        if( c != null ) {
197            return c.stream().filter(att -> name.equals(att.getFileName())).findFirst().orElse(null);
198        }
199
200        return null;
201    }
202
203    /**
204     * {@inheritDoc}
205     */
206    @Override
207    public Attachment getAttachmentInfo( final Page page, final String name, final int version ) throws ProviderException {
208        LOG.debug( "Getting attachments for {}, name={}, version={}", page, name, version );
209        //  We don't cache previous versions
210        if( version != WikiProvider.LATEST_VERSION ) {
211            LOG.debug( "...we don't cache old versions" );
212            return provider.getAttachmentInfo( page, name, version );
213        }
214        final Collection< Attachment > c = cachingManager.get( CachingManager.CACHE_ATTACHMENTS_COLLECTION, page.getName(),
215                                                               ()-> provider.listAttachments( page ) );
216        return findAttachmentFromCollection( c, name );
217    }
218
219    /**
220     * {@inheritDoc}
221     */
222    @Override
223    public List< Attachment > getVersionHistory( final Attachment att ) {
224        return provider.getVersionHistory( att );
225    }
226
227    /**
228     * {@inheritDoc}
229     */
230    @Override
231    public void deleteVersion( final Attachment att ) throws ProviderException {
232        // This isn't strictly speaking correct, but it does not really matter
233        cachingManager.remove( CachingManager.CACHE_ATTACHMENTS_COLLECTION, att.getParentName() );
234        provider.deleteVersion( att );
235        if( att.getVersion() == PageProvider.LATEST_VERSION ) {
236            attachments.decrementAndGet();
237        }
238    }
239
240    /**
241     * {@inheritDoc}
242     */
243    @Override
244    public void deleteAttachment( final Attachment att ) throws ProviderException {
245        cachingManager.remove( CachingManager.CACHE_ATTACHMENTS_COLLECTION, att.getParentName() );
246        cachingManager.remove( CachingManager.CACHE_ATTACHMENTS, att.getName() );
247        provider.deleteAttachment( att );
248        attachments.decrementAndGet();
249    }
250
251    /**
252     * Gets the provider class name, and cache statistics (misscount and hitcount of the attachment cache).
253     *
254     * @return A plain string with all the above-mentioned values.
255     */
256    @Override
257    public String getProviderInfo() {
258        return Synchronizer.synchronize(lock, () -> {
259            final CacheInfo attCacheInfo = cachingManager.info( CachingManager.CACHE_ATTACHMENTS );
260            final CacheInfo attColCacheInfo = cachingManager.info( CachingManager.CACHE_ATTACHMENTS_COLLECTION );
261            return "Real provider: " + provider.getClass().getName() +
262                    ". Attachment cache hits: " + attCacheInfo.getHits() +
263                    ". Attachment cache misses: " + attCacheInfo.getMisses() +
264                    ". Attachment collection cache hits: " + attColCacheInfo.getHits() +
265                    ". Attachment collection cache misses: " + attColCacheInfo.getMisses();
266        });
267
268    }
269
270    /**
271     *  Returns the WikiAttachmentProvider that this caching provider delegates to.
272     *
273     *  @return The real provider underneath this one.
274     */
275    public AttachmentProvider getRealProvider() {
276        return provider;
277    }
278
279    /**
280     * {@inheritDoc}
281     */
282    @Override
283    public void moveAttachmentsForPage( final String oldParent, final String newParent ) throws ProviderException {
284        provider.moveAttachmentsForPage( oldParent, newParent );
285        cachingManager.remove( CachingManager.CACHE_ATTACHMENTS_COLLECTION, newParent );
286        cachingManager.remove( CachingManager.CACHE_ATTACHMENTS_COLLECTION, oldParent );
287
288        // This is a kludge to make sure that the pages are removed from the other cache as well.
289        final String checkName = oldParent + "/";
290        final List< String > names = cachingManager.keys( CachingManager.CACHE_ATTACHMENTS_COLLECTION );
291        for( final String name : names ) {
292            if( name.startsWith( checkName ) ) {
293                cachingManager.remove( CachingManager.CACHE_ATTACHMENTS, name );
294            }
295        }
296    }
297
298}