/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.wicket.markup;
import java.util.Collection;
import java.util.Iterator;
import java.util.concurrent.ConcurrentHashMap;
import org.apache.wicket.Application;
import org.apache.wicket.MarkupContainer;
import org.apache.wicket.WicketRuntimeException;
import org.apache.wicket.util.lang.Args;
import org.apache.wicket.util.listener.IChangeListener;
import org.apache.wicket.util.watch.IModifiable;
import org.apache.wicket.util.watch.IModificationWatcher;
import org.apache.wicket.util.watch.ModificationWatcher;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* This is Wicket's default IMarkupCache implementation. It will load the markup and cache it for
* fast retrieval.
* <p>
* If the application is in development mode and a markup file changes, it'll automatically be
* removed from the cache and reloaded when needed.
* <p>
* MarkupCache is registered with {@link MarkupFactory} which in turn is registered with
* {@link org.apache.wicket.settings.MarkupSettings} and thus can be replaced with a sub-classed version.
*
* @see org.apache.wicket.settings.MarkupSettings
* @see MarkupFactory
*
* @author Jonathan Locke
* @author Juergen Donnerstag
*/
public class MarkupCache implements IMarkupCache
{
/** Log for reporting. */
private static final Logger log = LoggerFactory.getLogger(MarkupCache.class);
/** The actual cache: location => Markup */
private final ICache<String, Markup> markupCache;
/**
* Add extra indirection to the cache: key => location
* <p>
* Since ConcurrentHashMap does not allow to store null values, we are using Markup.NO_MARKUP
* instead.
*/
private final ICache<String, String> markupKeyCache;
/** The markup cache key provider used by MarkupCache */
private IMarkupCacheKeyProvider markupCacheKeyProvider;
/**
* Note that you can not use Application.get() since removeMarkup() will be called from a
* ModificationWatcher thread which has no associated Application.
*/
private final Application application;
/**
* A convenient helper to get the markup cache registered with the application.
*
* @see {@link Application#getMarkupSettings()}
* @see {@link MarkupFactory#getMarkupCache()}
*
* @return The markup cache registered with the {@link Application}
*/
public static IMarkupCache get()
{
return Application.get().getMarkupSettings().getMarkupFactory().getMarkupCache();
}
/**
* Constructor.
*/
protected MarkupCache()
{
application = Application.get();
markupCache = newCacheImplementation();
if (markupCache == null)
{
throw new WicketRuntimeException("The map used to cache markup must not be null");
}
markupKeyCache = newCacheImplementation();
}
@Override
public void clear()
{
markupCache.clear();
markupKeyCache.clear();
}
@Override
public void shutdown()
{
markupCache.shutdown();
markupKeyCache.shutdown();
}
/**
* Note that this method will be called from a "cleanup" thread which might not have a thread
* local application.
*/
@Override
public final IMarkupFragment removeMarkup(final String cacheKey)
{
Args.notNull(cacheKey, "cacheKey");
if (log.isDebugEnabled())
{
log.debug("Removing from cache: " + cacheKey);
}
// Remove the markup from the cache
String locationString = markupKeyCache.get(cacheKey);
IMarkupFragment markup = (locationString != null ? markupCache.get(locationString) : null);
if (markup == null)
{
return null;
}
// Found an entry: actual markup or Markup.NO_MARKUP. Null values are not possible
// because of ConcurrentHashMap.
markupCache.remove(locationString);
if (log.isDebugEnabled())
{
log.debug("Removed from cache: " + locationString);
}
// If a base markup file has been removed from the cache then
// the derived markup should be removed as well.
removeMarkupWhereBaseMarkupIsNoLongerInTheCache();
// And now remove all watcher entries associated with markup
// resources no longer in the cache.
// Note that you can not use Application.get() since removeMarkup() will be called from a
// ModificationWatcher thread which has no associated Application.
IModificationWatcher watcher = application.getResourceSettings().getResourceWatcher(false);
if (watcher != null)
{
Iterator<IModifiable> iter = watcher.getEntries().iterator();
while (iter.hasNext())
{
IModifiable modifiable = iter.next();
if (modifiable instanceof MarkupResourceStream)
{
if (!isMarkupCached((MarkupResourceStream)modifiable))
{
iter.remove();
if (log.isDebugEnabled())
{
log.debug("Removed from watcher: " + modifiable);
}
}
}
}
}
return markup;
}
private void removeMarkupWhereBaseMarkupIsNoLongerInTheCache()
{
// Repeat until all dependent resources have been removed (count == 0)
int count = 1;
while (count > 0)
{
// Reset prior to next round
count = 0;
// Iterate though all entries of the cache
Iterator<Markup> iter = markupCache.getValues().iterator();
while (iter.hasNext())
{
Markup markup = iter.next();
if ((markup != null) && (markup != Markup.NO_MARKUP))
{
// Check if the markup associated with key has a base markup. And if yes, test
// if that is cached. If the base markup has been removed, than remove the
// derived markup as well.
MarkupResourceStream resourceStream = markup.getMarkupResourceStream();
if (resourceStream != null)
{
resourceStream = resourceStream.getBaseMarkupResourceStream();
}
// Is the base markup available in the cache?
if ((resourceStream != null) && !isMarkupCached(resourceStream))
{
iter.remove();
count++;
if (log.isDebugEnabled())
{
log.debug("Removed derived markup from cache: " +
markup.getMarkupResourceStream());
}
}
}
}
}
}
/**
* @param resourceStream
* @return True if the markup is cached
*/
private boolean isMarkupCached(final MarkupResourceStream resourceStream)
{
if (resourceStream != null)
{
String key = resourceStream.getCacheKey();
if (key != null)
{
String locationString = markupKeyCache.get(key);
if ((locationString != null) && (markupCache.get(locationString) != null))
{
return true;
}
}
}
return false;
}
@Override
public final int size()
{
return markupCache.size();
}
/**
* Get a unmodifiable map which contains the cached data. The map key is of type String and the
* value is of type Markup.
* <p>
* May be used to debug or iterate the cache content.
*
* @return cache implementation
*/
public final ICache<String, Markup> getMarkupCache()
{
return markupCache;
}
@Override
public final Markup getMarkup(final MarkupContainer container, final Class<?> clazz,
final boolean enforceReload)
{
Class<?> containerClass = MarkupFactory.get().getContainerClass(container, clazz);
// Get the cache key to be associated with the markup resource stream.
// If the cacheKey returned == null, than caching is disabled for the resource stream.
final String cacheKey = getMarkupCacheKeyProvider(container).getCacheKey(container,
containerClass);
// Is the markup already in the cache?
Markup markup = null;
if ((enforceReload == false) && (cacheKey != null))
{
markup = getMarkupFromCache(cacheKey, container);
}
// If markup not found in cache or cache disabled, than ...
if (markup == null)
{
if (log.isDebugEnabled())
{
log.debug("Load markup: cacheKey=" + cacheKey);
}
// Get the markup resource stream for the container
final MarkupResourceStream resourceStream = MarkupFactory.get()
.getMarkupResourceStream(container, containerClass);
// Found markup?
if (resourceStream != null)
{
resourceStream.setCacheKey(cacheKey);
// load the markup and watch for changes
markup = loadMarkupAndWatchForChanges(container, resourceStream, enforceReload);
}
else
{
markup = onMarkupNotFound(cacheKey, container, Markup.NO_MARKUP);
}
}
// NO_MARKUP should only be used inside the Cache.
if (markup == Markup.NO_MARKUP)
{
markup = null;
}
return markup;
}
/**
* Will be called if the markup was not in the cache yet and could not be found either.
* <p>
* Subclasses may change the default implementation. E.g. they might choose not to update the
* cache to enforce reloading of any markup not found. This might be useful in very dynamic
* environments. Additionally a non-caching IResourceStreamLocator should be used.
*
* @param cacheKey
* @param container
* @param markup
* Markup.NO_MARKUP
* @return Same as parameter "markup"
* @see org.apache.wicket.settings.ResourceSettings#setResourceStreamLocator(org.apache.wicket.core.util.resource.locator.IResourceStreamLocator)
*/
protected Markup onMarkupNotFound(final String cacheKey, final MarkupContainer container,
final Markup markup)
{
if (log.isDebugEnabled())
{
log.debug("Markup not found: " + cacheKey);
}
// If cacheKey == null then caching is disabled for the component
if (cacheKey != null)
{
// flag markup as non-existent
markupKeyCache.put(cacheKey, cacheKey);
putIntoCache(cacheKey, container, markup);
}
return markup;
}
/**
* Put the markup into the cache if cacheKey is not null and the cache does not yet contain the
* cacheKey. Return the markup stored in the cache if cacheKey is present already.
*
* More sophisticated implementations may call a container method to e.g. cache it per container
* instance.
*
* @param locationString
* If {@code null} then ignore the cache
* @param container
* The container this markup is for.
* @param markup
* @return markup The markup provided, except if the cacheKey already existed in the cache, then
* the markup from the cache is provided.
*/
protected Markup putIntoCache(final String locationString, final MarkupContainer container,
Markup markup)
{
if (locationString != null)
{
if (markupCache.containsKey(locationString) == false)
{
// The default cache implementation is a ConcurrentHashMap. Thus neither the key nor
// the value can be null.
if (markup == null)
{
markup = Markup.NO_MARKUP;
}
markupCache.put(locationString, markup);
}
else
{
// We don't lock the cache while loading a markup. Thus it may
// happen that the very same markup gets loaded twice (the first
// markup being loaded, but not yet in the cache, and another
// request requesting the very same markup). Since markup
// loading in avg takes less than 100ms, it is not really an
// issue. For consistency reasons however, we should always use
// the markup loaded first which is why it gets returned.
markup = markupCache.get(locationString);
}
}
return markup;
}
/**
* Wicket's default implementation just uses the cacheKey to retrieve the markup from the cache.
* More sophisticated implementations may call a container method to e.g. ignore the cached
* markup under certain situations.
*
* @param cacheKey
* If null, than the cache will be ignored
* @param container
* @return null, if not found or to enforce reloading the markup
*/
protected Markup getMarkupFromCache(final String cacheKey, final MarkupContainer container)
{
if (cacheKey != null)
{
String locationString = markupKeyCache.get(cacheKey);
if (locationString != null)
{
return markupCache.get(locationString);
}
}
return null;
}
/**
* Loads markup from a resource stream.
*
* @param container
* The original requesting markup container
* @param markupResourceStream
* The markup resource stream to load
* @param enforceReload
* The cache will be ignored and all, including inherited markup files, will be
* reloaded. Whatever is in the cache, it will be ignored
* @return The markup. Markup.NO_MARKUP, if not found.
*/
private Markup loadMarkup(final MarkupContainer container,
final MarkupResourceStream markupResourceStream, final boolean enforceReload)
{
String cacheKey = markupResourceStream.getCacheKey();
String locationString = markupResourceStream.locationAsString();
if (locationString == null)
{
// set the cache key as location string, because location string
// couldn't be resolved.
locationString = cacheKey;
}
Markup markup = MarkupFactory.get().loadMarkup(container, markupResourceStream,
enforceReload);
if (markup != null)
{
if (cacheKey != null)
{
String temp = markup.locationAsString();
if (temp != null)
{
locationString = temp;
}
// add the markup to the cache.
markupKeyCache.put(cacheKey, locationString);
return putIntoCache(locationString, container, markup);
}
return markup;
}
// In case the markup could not be loaded (without exception) then ..
if (cacheKey != null)
{
removeMarkup(cacheKey);
}
return Markup.NO_MARKUP;
}
/**
* Load markup from an IResourceStream and add an {@link IChangeListener}to the
* {@link ModificationWatcher} so that if the resource changes, we can remove it from the cache
* automatically and subsequently reload when needed.
*
* @param container
* The original requesting markup container
* @param markupResourceStream
* The markup stream to load and begin to watch
* @param enforceReload
* The cache will be ignored and all, including inherited markup files, will be
* reloaded. Whatever is in the cache, it will be ignored
* @return The markup in the stream
*/
private Markup loadMarkupAndWatchForChanges(final MarkupContainer container,
final MarkupResourceStream markupResourceStream, final boolean enforceReload)
{
// @TODO the following code sequence looks very much like in loadMarkup. Can it be
// optimized?
final String cacheKey = markupResourceStream.getCacheKey();
if (cacheKey != null)
{
if (enforceReload == false)
{
// get the location String
String locationString = markupResourceStream.locationAsString();
if (locationString == null)
{
// set the cache key as location string, because location string
// couldn't be resolved.
locationString = cacheKey;
}
Markup markup = markupCache.get(locationString);
if (markup != null)
{
markupKeyCache.put(cacheKey, locationString);
return markup;
}
}
// Watch file in the future
final IModificationWatcher watcher = application.getResourceSettings()
.getResourceWatcher(true);
if (watcher != null)
{
watcher.add(markupResourceStream, new IChangeListener()
{
@Override
public void onChange()
{
if (log.isDebugEnabled())
{
log.debug("Remove markup from watcher: " + markupResourceStream);
}
// Remove the markup from the cache. It will be reloaded
// next time when the markup is requested.
watcher.remove(markupResourceStream);
removeMarkup(cacheKey);
}
});
}
}
if (log.isDebugEnabled())
{
log.debug("Loading markup from " + markupResourceStream);
}
return loadMarkup(container, markupResourceStream, enforceReload);
}
/**
* Get the markup cache key provider to be used
*
* @param container
* The MarkupContainer requesting the markup resource stream
* @return IMarkupResourceStreamProvider
*/
public IMarkupCacheKeyProvider getMarkupCacheKeyProvider(final MarkupContainer container)
{
if (container instanceof IMarkupCacheKeyProvider)
{
return (IMarkupCacheKeyProvider)container;
}
if (markupCacheKeyProvider == null)
{
markupCacheKeyProvider = new DefaultMarkupCacheKeyProvider();
}
return markupCacheKeyProvider;
}
/**
* Allows you to change the map implementation which will hold the cache data. By default it is
* a ConcurrentHashMap() in order to allow multiple thread to access the data in a secure way.
*
* @param <K>
* @param <V>
* @return new instance of cache implementation
*/
protected <K, V> ICache<K, V> newCacheImplementation()
{
return new DefaultCacheImplementation<K, V>();
}
/**
* MarkupCache allows you to implement you own cache implementation. ICache is the interface the
* implementation must comply with.
*
* @param <K>
* The key type
* @param <V>
* The value type
*/
public interface ICache<K, V>
{
/**
* Clear the cache
*/
void clear();
/**
* Remove an entry from the cache.
*
* @param key
* @return true, if found and removed
*/
boolean remove(K key);
/**
* Get the cache element associated with the key
*
* @param key
* @return cached object for key <code>key</code> or null if no matches
*/
V get(K key);
/**
* Get all the keys referencing cache entries
*
* @return collection of cached keys
*/
Collection<K> getKeys();
/**
* Get all the values referencing cache entries
*
* @return collection of cached keys
*/
Collection<V> getValues();
/**
* Check if key is in the cache
*
* @param key
* @return true if cache contains key <code>key</code>
*/
boolean containsKey(K key);
/**
* Get the number of cache entries
*
* @return number of cache entries
*/
int size();
/**
* Put an entry into the cache
*
* @param key
* The reference key to find the element. Must not be null.
* @param value
* The element to be cached. Must not be null.
*/
void put(K key, V value);
/**
* Cleanup and shutdown
*/
void shutdown();
}
/**
* @param <K>
* @param <V>
*/
public static class DefaultCacheImplementation<K, V> implements ICache<K, V>
{
// Neither key nor value are allowed to be null with ConcurrentHashMap
private final ConcurrentHashMap<K, V> cache = new ConcurrentHashMap<K, V>();
/**
* Construct.
*/
public DefaultCacheImplementation()
{
}
@Override
public void clear()
{
cache.clear();
}
@Override
public boolean containsKey(final Object key)
{
if (key == null)
{
return false;
}
return cache.containsKey(key);
}
@Override
public V get(final Object key)
{
if (key == null)
{
return null;
}
return cache.get(key);
}
@Override
public Collection<K> getKeys()
{
return cache.keySet();
}
@Override
public Collection<V> getValues()
{
return cache.values();
}
@Override
public void put(K key, V value)
{
// Note that neither key nor value are allowed to be null with ConcurrentHashMap
cache.put(key, value);
}
@Override
public boolean remove(K key)
{
if (key == null)
{
return false;
}
return cache.remove(key) == null;
}
@Override
public int size()
{
return cache.size();
}
@Override
public void shutdown()
{
clear();
}
}
}