MarkupCache.java

/*
 * 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();
		}
	}
}